Technotools

home *** CD-ROM | disk | FTP | other *** search

/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / batch / get25 / get.doc < prev next >

Wrap

Text File | 1991-11-29 | 160.9 KB | 3,527 lines

GET.EXE Bob Stephan's BATch Enhancer Version 2.5 November 1991 Copyright 1991, Bob Stephan All Rights Reserved For information or orders contact: MOBY DISK Phone: 1-408-646-1899 1-408-646-1373 GENIE: MOBYDISK COMPUSERVE: 72357,2276 Bob Stephan on CRICKET BBS: 1-408-373-3773 Monterey Bay Disk Data Systems Attn: Bob Stephan 1021 San Carlos Road Pebble Beach, CA 93953 GET.DOC GET Version 2.5 Copyright 1991 Bob Stephan READ.ME GET.EXE is a general purpose DOS BATch file enhancer. It makes informa- tion available to the BATch file through the BATch IF subcommand. The information can come from user input or from the operating system, and it is made available to the BATch file through the DOS ErrorLevel (Exit Code) and variables in the DOS master Environment. GET also has capabil- ities to set some system parameters and perform a few other specific ac- tions, over 30 functions in all. Not only is GET wonderful for automat- ing your personal system, it is excellent for client support and soft- ware installation programs. If you have been using an older version of GET, you will also be interested in the information in GET25NEW.DOC to help focus on the new and improved features. LICENSING SUMMARY GET is copyrighted software and is not in the public domain! GET is not totally free for all users, and there are conditions imposed on its dis- tribution. Please read this information and the section on Licensing and Distribution to be sure you are not using GET illegally. The only version of GET that is free is the one that displays the help screen when the name GET is entered at the DOS prompt by itself. If you have one that says it is licensed and you have not registered, you have a pirated copy that is protected by law. VENDORS, CORPORATE, and COMMERCIAL users see licensing terms under Licens- ing and Distribution. INDIVIDUALS, SHAREWARE AUTHORS, and SYSOPS. For individuals this version of GET is free for personal use, and for the use of shareware authors in distributing their products subject to the conditions specified in the Licensing and Distribution terms below. GET.EXE may be freely copied and distributed provided that all files in the GET package, including but not limited to GET.DOC and GET25NEW.DOC, are included on the disk or in the compressed file with GET.EXE. Contributions to support this de- velopment project will be gratefully accepted. If you use GET and can't send money, at least send thanks. Programmers do not live by bread alone. Besides, I'll put you on the list to help me distribute new releases as they become available. If you send $15 or more (overseas $20 U.S. funds) you will receive the following benefits: (California residents please add 7.75% sales tax.) The latest version of GET with any new features plus one free upgrade. A smaller runtime version to distribute with your BATch files. A single user license with no royalties for use of the runtime version. A >60 page user manual giving examples and detailed explanations. Free support by BBS, mail, phone, CompuServe, or Genie (see below). Notification of new releases and upgrades after the first one. If you have a modem, VISA and MASTERCARD registrations can be entered via NITELOG BBS, 408-655-1096. After completing the brief sign-on registra- tion, enter S for Script, then 3 for Script 3. If you have any questions, comments, or suggestions please contact me at: MOBY DISK: 1021 San Carlos Road, Pebble Beach, CA 93953 Phone: (408) 646-1899/1373. GENIE:MOBYDISK. COMPUSERVE:72357,2276 BBS: The Cricket 408-373-3773 /s/ Bob Stephan November 29, 1991 GET.DOC Table of Contents Page ii Table of Contents READ.ME....................................................................i LICENSING SUMMARY..........................................................i Vendors, Corporate, and Commercial Users.................................i Individuals, Shareware Authors, and SYSOPS...............................i VISA and MASTERCARD........................................................i SYSTEM REQUIREMENTS........................................................1 ACKNOWLEDGMENTS............................................................1 ABOUT THE AUTHOR...........................................................2 LIMITED WARRANTY (and other legalities)....................................2 HELP SCREEN................................................................3 ENTERING COMMANDS..........................................................5 SEE HOW IT RUNS............................................................5 SYNTAX EXPLANATIONS........................................................6 Command..................................................................6 Argument(s)..............................................................6 [] brackets............................................................6 "" double quotes.......................................................6 filespec...............................................................6 chars..................................................................6 #......................................................................6 num, div...............................................................6 Environment..............................................................6 ErrorLevel...............................................................7 Extended.................................................................7 Surrogates...............................................................7 Switches.................................................................7 ERRORLEVEL.................................................................8 SWITCHES..................................................................10 /A...........................Prompt Attribute...........................10 /B.........................Flush Keyboard Buffer........................11 /C..........................Suppress Ctrl-Break.........................11 /E.............................Enhanced Keys............................11 /L...............................Lowercase..............................11 /M..........................Master Environment..........................11 /TR..............................Trim Right.............................11 /TL..............................Trim Left..............................11 /U...............................Uppercase..............................12 /V.............................Variable Name............................12 /W............................Wait or Number............................12 /X....................Extended Keys or eXtra function...................12 /~..........................GET S Escape Action.........................13 USING GET COMMANDS........................................................14 STRING HANDLING AND SCREEN I/O............................................14 GET C...........................GET Character...........................18 GET N.........................GET yes/no aNswer.........................21 GET T............................Moving Text............................23 GET S.............................GET String............................25 GET I..........................Check Key Buffer.........................28 GET Z..........................Put String (Zap).........................30 GET ZE..........................Standard Input..........................32 GET R.............................'Rithmetic............................34 GET B........................Clear (Blank) Screen.......................36 GET V.........................Get/set video mode........................37 GET VE.......................Get/set video border.......................38 GET H...........................Date and Time...........................39 GET U..........................Keyboard BUffer..........................42 Page iii Table of Contents GET.DOC GET UE............................Shift Locks...........................44 GET DISK and FILE Information.............................................45 GET K........................Get disk free space........................45 GET Q.....................Get Disk Capacity (Quota).....................47 GET L..........................Get volume label.........................49 GET LE........................Match volume label........................51 GET F...........................Get file size...........................52 GET Y.........................Current Directory.........................56 GET YE...........................Logged Drive...........................56 GET MEMORY and SYSTEM Information.........................................58 GET BR........................Get/Set Break Flag........................58 GET P.......................Check for Printer(PRN)......................59 GET PE......................Initialize Printer(PRN).....................59 GET E........................Get Environment Left.......................60 GET M..........................Get Memory Free..........................61 GET D..........................Get DOS Version..........................62 GET 7.........................Check Coprocessor.........................63 GET 7E..........................Check CPU Type..........................63 GET 4.........................Check 4DOS Status.........................64 GET 4E.......................Check Windows Status.......................64 GET A.........................Check for ANSI.SYS........................65 GET AE.....................Check for ROM BIOS Model.....................65 GET W...........................Warm/Cold Boot..........................66 Environment and Shells....................................................67 PROGRAM INFORMATION.......................................................68 LICENSING AND DISTRIBUTION................................................68 Corporate Users.........................................................68 SYSOPs, User Groups, and Shareware authors..............................69 Vendors.................................................................69 Registered Users........................................................69 Now for the commercial....................................................69 SPECIAL OFFER.............................................................70 Appendix A.......................The DOS Environment.....................A-1 Appendix B.......................ASCII and Scan Codes....................B-1 GET.DOC INTRODUCTION Page 1 INTRODUCTION BATch programming can make your computing life easier. BATch programming with GET can make your BATch programming much easier and more produc- tive. Most versions of DOS do not support a wide variety of useful fea- tures in the BATch programming commands that are available. GET supple- ments these commands, and gives BATch the capabilities it needs to real- ly do a proper job as a macro language. GET provides additional commands in four general areas: String Handling and Screen I/O Commands Disk and File Commands Memory and System Commands The commands are fully described herein, along with some general informa- tion on BATch programming and the use of ErrorLevel and the DOS Environ- ment. However, this is not a BATch programming tutorial or primer. Many useful books and publications can give you startup help if you need it. Among those that I am familiar with are "MS-DOS Batch File Program- ming" by Ronny Richardson, Windcrest, 2nd Ed. 1990, and "DOS Power Tools" mentioned below. SYSTEM REQUIREMENTS GET is compatible with all computers running under DR, MS or PC-DOS Ver- sions 2.0 and later, although 3.1 or later is preferred. It requires only about 11K of memory and is stored on disk in a smaller compressed format. It is not memory resident (TSR) and will not reduce the amount of memory available to other programs. It supports all types of monitors and display adapters whether monochrome or color. To support the many features of GET it is preferable if you are running DOS 3.1 or later. A few of the features may not work on earlier ver- sions, or with some of the early XT and AT ROM BIOS's. Where these limitations are known, they are mentioned in this document. ACKNOWLEDGMENTS My thanks to members of MBUG-PC, The Monterey Bay Users' Group - Per- sonal Computer, for their indulgence during my development of this sys- tem. Many members have used preliminary versions and offered their com- ments and suggestions. I am particularly grateful to the beta testers who held my feet to the fire to ensure that this would be a reliable and useful product. Among those in MBUG-PC who have been particularly help- ful are (in alphabetical order) Fred Brownell, Fred Huddle, Lee Keely, Jim Robeson, and Luther Schliesser. Others who have been very helpful are Kevin Paddock and Steve Ferg. I am also grateful to Bantam Computer Books for including GET in the Revised Second Edition of "DOS Power Tools," and Ronny Richardson for including it in his book mentioned above. Page 2 INTRODUCTION GET.DOC ABOUT THE AUTHOR Bob Stephan has been using and programming computers for over 25 years, mostly for other companies and for his own use and enjoyment. Shareware is his first independent commercial venture (see the commercial at the end of this document). He has been a mainstay in his local computer users group for over 8 years and is a past president as well as an au- thor of informative articles for the newsletter, leader of special in- terest groups, and provider of help to members on a variety of topics. LIMITED WARRANTY (and other legalities) Bob Stephan warrants the physical diskette and physical documentation pro- vided with the registered version to be free of defects in materials and workmanship for a period of sixty days from the purchase date. The entire and exclusive liability and remedy for breach of this Limited Warranty shall be limited to replacement of the defective diskette or documentation and shall not include or extend to any claim for or right to recover any other damages, including but not limited to loss of prof- it, data, or use of the software, or special, incidental, or consequen- tial damages or other similar claims. In no event will any liability for damages ever exceed the registration fee actually paid for the li- cense to use the software, regardless of any form of the claim. Bob Stephan specifically disclaims all other warranties, express or implied, including but not limited to, any implied warranty of merchantability or fitness for a particular purpose. Be that as it may, I claim that this software will perform substantially as detailed in this documentation when used on a machine with compatible software (DOS) and compatible firmware (ROM BIOS). If it does not work as documented when used in conformance with this documentation, I will either fix it if it is broken or refund your registration fee. If you are not satisfied, return the original registered disk and documentation within 30 days for a full refund of the registration fee paid. DR DOS, MS DOS, and 4DOS are trademarks of their respective companies. GET.DOC HELP SCREEN Page 3 HELP SCREEN If you enter GET at the DOS prompt by itself, or with any invalid argument such as a question mark, it will display the following summary of all GET commands: ╔══════════════════════════════════════════════════════════════════════════════╗ ║ GET Version 2.5 - BATch File Enhancer - Copyright 1991 Bob Stephan ║ ║ Syntax: GET command argument(s) /switches More Instructions: GET.DOC ║ ║Purpose Command Argument(s) Environment ErrorLevel Extended ║ ║--------- ------- ----------- --(GET=)--- --(Exit)-- --[E]--- ║ ║ --------- String Handling and Screen I/O Commands -------- ║ ║Get character(InKey)C[E] ["prompt"][chars] Character ASCII code No Echo ║ ║Get yes/no aNswer N[E] ["prompt"][seconds] Character ASCII code No Echo ║ ║Get string S[E] ["prompt"][pattern] String Length No Echo ║ ║Put string (Zap) Z[E] ["string/prompt"] String Length StdInput ║ ║Moving Text(GetaKey)T[E] "filespec" [chars] Character ASCII code No Echo ║ ║Key check (IsKey) I[E] Char.Waitng Char.Waitng Get Char ║ ║Date and Time H[E] 1=DoW 2=DoM 4=Mon 8=Yr 16=Hr 32=Min 64=Sec Sum/Cat ║ ║Keyboard BUffer U[E] ["chars"][num][/Wnum] -- Length Caps/Num ║ ║'Rithmetic (add) R[E] [num] [/Wnum] Sum/Diff Sum/Diff Subtract ║ ║Clear (Blank) Screen B[E] [New attribute] Old attribute HexAttr ║ ║Video mode/VGA border V[E] [New mode/color] Old mode/color VGA Border║ ║ --------- Disk and File Commands -------- ║ ║Get file size (DIR=0) F[E] filespec[/WdivXA]Bytes/Hex Kilobytes Kb/10 ║ ║Get disk free space K[E] [drive] [/Wdiv] Kilobytes Kb/10 Kb/100 ║ ║Get disk capacity Q[E] [drive] [/Wdiv] Kilobytes Kb/10 Kb/100 ║ ║Get volume label L[E] ["label"][drive] Label 1=yes,0=no Match ║ ║Get current directory Y[E] [drive for Y] Directory Level/Drive Drive:A=0║ ║ --------- Memory and System Commands -------- ║ ║Get Environment left E[E] Bytes left Bytes left Bytes/10 ║ ║Get memory free M[E] Kilobytes Kilobytes Kb/10 ║ ║Get/Set Break Flag BR [New flag 1=on, 0=off] Old flag None ║ ║Check for printer(PRN) P[E] 1=yes,0=no 1=yes,0=no Initialize║ ║Check 4DOS/Windows 4[E] 1=yes,0=no 1=yes,0=no Windows ║ ║Get DOS version D[E] Major Vers. MajorMinor MinorEnv ║ ║Check coprocessor/CPU 7[E] 1=yes,0=no 1=yes,0=no CPU Type ║ ║Check ANSI.SYS/Model A[E] 1=yes,0=no 1=yes,0=no PC Model ║ ║Warm/Cold Boot W[E] If argument given then 1=warm, 0=cold ColdBoot ║ ║ Surrogates: }=Carriage Return, ~=Escape, Alt-255=Space/Blank. ║ ║ SWITCHES: /C Ctrl-Break, /U /L case, /M Master Env, /E Enhanced keys, /Vvar= ║ ║ /X eXtended keys/Hex, /A[nnn] prompt Attribute, /W[nnnn] Wait seconds/div ║ ║ /B flush key Buffer, /TL /TR Trim, /~ Escape action for GET S, /V- No var ║ ║ See GET.DOC for additional features and BATch programming instructions. ║ ╚══════════════════════════════════════════════════════════════════════════════╝ Displaying the help screen by simply entering GET will now pause at the end of the second screen with the message Press PgUp to repeat the first screen - Esc, CR, or space bar to exit Pressing PgUp at this point will start the help screen display over again. Pressing CR (Enter or Return on the keyboard) will exit and clear the screen giving you a clear screen to work on. Pressing Esc or the space bar will exit and leave the second help screen on the display for reference. The pause will time out in 10 seconds and return to the DOS prompt automatically. GET.DOC HELP SCREEN Page 4 You can make a file copy of this Help Screen by using DOS redirection. Enter the command GET >GET.HLP. When you see the --More-- prompt, press Enter again. This Help Screen will be in the file GET.HLP. When you are BATch programming, put the help file in one of your editor's windows where you can use it for quick reference. GET.DOC ENTERING COMMANDS Page 5 ENTERING COMMANDS GET is used in BATch files. When you want to use GET in a BATch file use the following simple procedure: 1. Enter the word GET as the first entry on a line, followed by a space. 2. Tell GET what it is that you want it to get for you. Do this by selec- ting and entering a one or two letter command from the Command column on the HELP SCREEN. All of the commands are described in this document. 3. If there are arguments, enter a space and then the arguments that you need or want to run the command. 4. If you want to use any of the /switches, enter them on the same line after all argument(s). 5. On the next line of the BATch file, check the return from GET in the ErrorLevel and/or the GET= variable in the Environment. The Environment variable can be accessed as %GET% or by the name you give it with the /V switch described below. For example, to get a yes or no answer you might enter the lines: :Ask GET N "Answer yes or no: " IF "%GET%"=="N" goto NO IF "%GET%"=="Y" goto YES Rem The next line checks to see if the user pressed Escape if ErrorLevel 126 goto END ECHO You must enter Y or N, or press Esc to exit. goto ASK :NO Rem [Do what you need to do if the user enters N] goto END :YES Rem [Do what you need to do if the user enters Y] :END The next line clears GET out of the Environment. set GET= SEE HOW IT RUNS The best way to find out how GET works is to just try it. You can try it from the command line by using the special built-in reporting feature. To see what GET is putting in the ErrorLevel and the Environment, issue the DOS command SET GET?=ON. This will tell GET to report the results to the screen in addition to placing them in the ErrorLevel and the En- vironment. Then run the GET commands that you want to check out, or run your BATch file to see what GET reports. You can also try GET from the command line if you use SET (by itself) to check what has been placed in the Environment, but to find out what is in the ErrorLevel, you must use a BATch file unless you SET GET?=ON. If you are not familiar with the DOS Environment, see the discussion of En- vironment and Shells elsewhere in this documentation. Page 6 ENTERING COMMANDS GET.DOC SYNTAX EXPLANATIONS (Refer to the HELP SCREEN) Command: Commands are one or two character combinations as shown on the HELP SCREEN. Single character commands can [optionally] be immediately followed by E with no spaces between. The E indicates the Extended function in the last column on the HELP SCREEN. Argument(s): Arguments are zero, one, or two character strings as ap- propriate to the command. A "string" is a sequence of consecutive ASCII characters delimited by double quotes or, if not in quotes, by the space character. In some cases the first, or only, argument must be enclosed in double quotes as shown on the HELP SCREEN. Arguments that are not shown in quotes on the HELP SCREEN must not be put in quotes. Each character string can consist of zero or more ASCII characters. The blank or space character (ASCII 32) delimits the character strings that are not in quotes. The space character can only be a member of one of the strings that is enclosed in double quotes. (In this document, both "blank" and "space" are used as synonyms for the ASCII-32 character.) [] brackets indicate optional portions of commands and/or arguments. The command will work regardless whether these portions are included or not. The brackets themselves must not be included! " Where double quotes ("'s) are shown, they must be included if the corresponding prompt, string, or filespec argument is used. filespecs consist of a filename and extension as appropriate to the DOS file naming conventions. They may include drive and path but no wild- cards in the general form of d:\path\filename.ext. chars refers to an ASCII character string which can include any of the ASCII characters from decimal 33 to decimal 255 inclusive, but some of these characters have special significance. Blanks can only be used in strings that must be enclosed in double quotes (but see the use of surrogates below.) IMPORTANT: All characters in the chars argument must be in a contiguous string with no blanks, including any surrogate characters! If you want to specify the space character use the Alt- 255 surrogate. # is now obsolete. Although it is still supported in Version 2.5 for compatibility, it must be replaced with the /W syntax because # will not be supported in future versions. The new and preferred method is to use the /W switch. Note that because of this special significance, # cannot be used as an input character in the chars string. num and div must be entered as ASCII decimal digit characters represent- ing a number containing no more than 4 digits. The new preferred syntax is to use the /W switch to enter numbers where the old syntax was #num or #div. Environment: this column indicates what will be found in the Environment string GET= or the one you name with the /V switch. This string can be accessed from a BATch file with the %GET% notation. It is best to en- close %GET% in double quote characters in case it is empty. For exam- ple: IF "%GET%"=="" will check for an empty GET variable. The variable name can be changed with the /V switch described below. If you need more information on testing Environment variables, see the section on Environment and Shells later in this document. GET.DOC ENTERING COMMANDS Page 7 ErrorLevel: this column indicates what value will be placed in the DOS Er- rorLevel where it can be accessed in BATch files with the "IF Error- Level" subcommand. Always check for ErrorLevel from highest to lowest values of interest. ErrorLevel is also referred to as Exit Code or Return Code. If you need more information on testing the ErrorLevel, see the next section on ERRORLEVEL. Extended: this column indicates the action taken if the optional E for [E]xtended command is included. Do not include the brackets! In most cases E applies to either the result in the Environment or the result in the ErrorLevel, but not to both. In a few cases the E invokes a sepa- rate but loosely related function. Surrogates: Some characters are awkward or impossible to handle directly in BATch files. For example, BATch files generally use the carriage return <CR> and space characters as delimiters instead of as ASCII characters that can be manipulated. Some special symbols have been designated to facilitate the handling of these characters. These sub- stitutions may have different meanings depending on the command being used, so read the description of the command. The special characters are: Carriage Return: } is used for CR Escape: ~ is used for Esc Blank: Alt-255 is used for Space (Blank). The Alt-255 character can be entered in most text editors by holding down the Alt key while spelling out the digits for the character on the number pad of the keyboard, but check your text editor for this capabil- ity. It is often convenient to ask the user to press the space bar. The blank (or space) surrogate, Alt-255, makes it possible to check for a space. In most versions of DOS the subcommand IF "%GET%"==" ", or any comparison of strings which include spaces, does not work properly since DOS uses the space as a delimiter. By using Alt-255 as a surrogate for the space character, WYSIWYG is maintained, and the character can be manipulated like any alphabetic character. 4DOS, however, treats strings in double quotes properly. Switches are special modifiers to GET commands. A switch is indicated by the forward slash character, "/", immediately followed by the ap- propriate letter or character. See SWITCHES, page 10. Page 8 The Error Level GET.DOC ERRORLEVEL If you are not familiar with testing for the ErrorLevel in BATch files, read this section. If the ErrorLevel holds no mysteries for you, then skip to the next section. To test a program to determine what ErrorLevel(s) it returns, use RUN.EXE included in GET25.ZIP. See RUN.DOC for details. Most modern programs that run under DOS issue a numeric status code which is passed back to DOS when they terminate. This is variously referred to as a "return code", "exit code", "status code", "error code", "Error Level", etc.. An "ErrorLevel" is simply that code, whatever it may be called. Generally, an errorlevel of 0 means a normal, successful completion, and a non-zero return code indicates a problem of some sort. GET uses the Er- rorLevel for different purposes to pass information back to the BATch file in such a way that the BATch file can make use of it with the IF ERROR- LEVEL subcommand. IF ERRORLEVEL is one of the cases of the IF statement. It tests the return code from the program for some condition that you specify. The various IF tests always result in a true/false result - either the test is true or it is false. If it is true, the statement following the IF test on the same line is executed, otherwise it is ignored. The IF ERRORLEVEL test is al- ways a "greater than or equal" test, or in BASIC parlance >=. So when you enter IF ERRORLEVEL 5 DO SOMETHING, it means "if the return code from the previous program is greater than or equal to 5" the BATch file is to do something, otherwise it will ignore the rest of the line starting with IF. To test specifically for an ErrorLevel of 0 you use the NOT parameter for the IF subcommand. So when you enter IF NOT ERRORLEVEL 1 DO SOMETHING ELSE, it means "if the return code is not greater than or equal to 1 do something else." Since return codes can only be integers 0 through 255, a return code that is not >= 1, can only be 0, hence the test for Error- Level=0. ERRORLEVEL tests can be "and"ed to test for a specific return code. If you enter IF ERRORLEVEL 5 IF NOT ERRORLEVEL 6 DO STILL ANOTHER THING, it means "if the return code is greater than or equal to 5 but not greater than or equal to 6 do still another thing." The only integer that satisfies those conditions is 5 itself. Not all programs return error levels. DOS itself is the worst offender. No internal commands that I know of return codes, and not all the external commands are so thoughtful. Later versions of DOS are getting better about returning and documenting such codes, but unless it is documented that a code is returned and what it signifies, there is no way to assume that one is available. To find out what a return code means you must read the documentation for the program or command. If there is a possibility of several return codes, the IF ERRORLEVEL tests must be used in descending order because of the >= meaning. For example, the MS DOS 5.0 FORMAT command is documented to have the following "exit codes." 0 The format operation was successful. 3 The user pressed Ctrl-C to stop the process. 4 A fatal error occurred (any error other than 0, 3, or 5). GET.DOC The Error Level Page 9 5 The user pressed N in response to the prompt "Proceed with Format(Y/N)?" to stop the process You can set up a BATch file to automate the FORMATTING process, then check to see if it was successful. A portion of your BATch file might look like this: :AGAIN FORMAT %1 %2 %3 if ErrorLevel 5 goto DONE if ErrorLevel 4 goto ERROR if ErrorLevel 3 goto ASK Rem If it wasn't one of the above, it has to be 0, Rem so go back to see if you want to do it again. goto AGAIN :ERROR Come here if a fatal error occurred - code=4. ECHO The FORMAT command failed! :ASK Come here if the ErrorLevel was 3 - user pressed Ctrl-C GET N "Do you want to try another disk?" if "%GET%"=="Y" goto AGAIN :DONE Echo The FORMAT operation has been completed! Echo Have a good day. Page 10 SWITCHES GET.DOC SWITCHES Switches are special modifiers to GET commands. A switch is indicated by the forward slash character, "/", immediately followed by the appropriate letter or character. More than one switch may be used with a command, and all switches must come after any other arguments. Switches that are not applicable to a command will be ignored and not cause any harm if in- advertently included. Some switches replace the "surrogate" character syntax that was used in GET Version 2.2 and earlier. The old syntax has been retained in Version 2.5 for compatibility, but will be eliminated in future versions. Where the switches duplicate other features, the switch is the preferred method. The switches that have been implemented in Release 2.5 are /A, /B, /C, /E, /L, /M, /TR, /TL, /U, /V, and /W. /A lets you control the screen attribute of prompts. The prompts can be displayed in reverse video, or any of 254 color combinations that are available on color monitors. /A by itself causes the prompt to be dis- played in reverse video. /Annn, where nnn is a number between 1 and 254 specifies the attribute to be used for the prompt. The following table explains how to construct the attribute. It is not necessary to have ANSI.SYS or any of its clones loaded to display prompts with attributes. The color codes are: 0 Black 2 Green 4 Red 6 Brown 1 Blue 3 Cyan 5 Magenta 7 White For the foreground color for the characters: 1. Select the color number from the above table. 2. For high intensity (bright or light), add 8. 3. For Blinking, add 128. Example: Blinking, high-intensity magenta is 5+8+128=141 For the background color: 1. Select the color number from the above table. 2. Multiply it by 16. 3. Add it to the foreground color. Example: Blinking, high-intensity magenta on white is 141+(7*16)=253 GET C "This is in blinking, high-intensity, magenta on white " /A253 With some command processors (4DOS is one), there can be a minor problem if the user presses break when the prompt is displayed on the bottom line of the screen if using GET ZE for input. If you are using GET ZE for in- put, you probably don't want to use /A to specify an attribute for the prompt. This will prevent the prompt color from being taken by DOS as the new color to use for scrolling the screen if the user presses a break key. As mentioned above, you can use /A to echo text to the screen in color. Any of the commands that display a prompt can do it if you specify 0 sec- onds to wait. GET I does not wait anyway, and it will display a prompt if there is one specified, so it is a good choice to use for the Echo command because you do not have to remember to specify /W0. In Version 2.5, if the /A switch is not included, the prompt will be dis- played in such a manner that ANSI sequences can be used for screen con- trol. This restores compatibility with Version 2.2 for prompting and using ANSI screen control sequences. The "prompt" will always be sent to GET.DOC SWITCHES Page 11 the screen even if standard output is redirected with DOS redirection (>). Without /A the prompt can be as long as will fit on the DOS command or BATch line which is limited to 128 characters total. With /A, the prompt is limited to 79 characters. /B flush keyboard Buffer. Useful to flush any type-ahead keystrokes when asking for user input. /C tells GET to handle Ctrl-C and Ctrl-Break instead of letting DOS do it. It has the same effect as the old Alt-253 which has been retained for com- patibility. The switch is preferred. See the GET USER INPUT section for additional details. Example: GET SE "Enter your password: " /C. Caution: The old Alt-253 surrogate will be eliminated in future versions. /E specifies that keystrokes will be read from the Enhanced keyboard. This has the same effect as the old surrogate for the enhanced keyboard, Alt- 254, which has been retained for compatibility in this version. /E only affects the C, N, I, and T commands. Also, note the discussion of the handling of the extended and enhanced keys by using scan codes and upper ASCII characters. Example: GET C "Enter F11 to continue: " Θ /E Caution: The old enhanced surrogate will be eliminated in future versions. NOTE: Extended keys are those with no ASCII representation, such as the function and cursor keys. Enhanced keys are keys on the enhanced keyboard which do not appear on older keyboard layouts, such as F11 and F12. /L specifies that the string that is written to the Environment is to be forced into lower case. Any ASCII-255 characters will be "lowercased" to the ASCII space character. Strings with spaces in them will not test properly with the BATch IF subcommand. Also: see /U for Uppercase. Example: GET SE "Enter your password: " /C /L /M tells GET to try to put the string in the master environment instead of the child environment. If the BATch file is being run from a secondary shell, GET will bypass the environment of the secondary command processor and look for the master environment. This works exactly like the old GET Z, and it makes GET Z more flexible. Without /M, GET Z will put the quoted string into the first command processor environment that it finds. If you want GET Z to work like it did in Version 2.2, you must add the /M switch. The advantage is that /M can be used with any GET command. If you need more information about the different environment areas see the section on ENVIRONMENT AND SHELLS. Example: GET Z "Put this string in the master environment" /M Caution: Finding the master environment is not a documented feature of DOS, and there is no guarantee that /M will work under all conditions. For ex- ample, don't expect it to work if the command processor is running in a DESQview window or under Windows, and it may cause the system to hang. If you need this capability, be sure to test it under all possible conditions before relying on it. /TR and /TL trim blanks from the string that is written to the environment. Trim works with S, SE, Z, ZE, and HE. /TR or /T+ will trim blanks from the right or trailing end of the string, while /TL or /T- will trim blanks from the left or leading end of the string. Both switches may be used in the same command if desired. Page 12 SWITCHES GET.DOC /U specifies that the string that is written to the Environment is to be forced into upper case (Caps). Any spaces will be "uppercased" to ASCII 255 so that the string can be tested with the BATch IF subcommand. /U is not necessary with the C, N, I, or T commands. Also: see /L for Lower- case. Example: GET SE "Enter your password: " /C /U /Vvar= lets you specify a name for the Environment variable to be used in place of "GET". This can eliminate some BATch file lines that would be used to save the GET variable under another name with the SET command. The name must be contiguous with the V in /V and should be terminated with the = sign. Although the '=' sign is optional, the name must be terminated in some way, and the '=' sign is the recommended method. How- ever, any one of the following characters will serve as the terminating delimiter for the name: =, space, /, or carriage return (indicating the end of the command line or BATch file line). Lowercase letters will be coerced to uppercase before placing the name in the Environment. The fol- lowing example will establish an Environment variable that will show up as DEMO= instead of the default name GET=. Example (old method): GET C "Enter the drive letter: " ABCD set DEMO=%GET% Example (new method): GET C "Enter the drive letter: " ABCD /vdemo= CAUTION: If you modify BATch files to take advantage of the convenience of the /V switch, be sure you adjust all references to the %GET% variable in subsequent statements to reflect the new variable name. /V- completely suppresses creating the Environment variable under any name. No changes to the Environment will be made. This is useful when the result is of no interest, or when all the information required can be ob- tained from the ErrorLevel. This may be useful at times when there is in- sufficient free space in the Environment, or when there is reluctance to create an Environment variable which might overwrite one that is already there. NOTE: A side effect of /V- is that SET GET?=ON will have no effect. Since the search of the Environment is being completely bypassed, GET cannot check for the GET? variable. /W has different meanings for different commands. In general it is always used to input a number for use by the command. When getting user keyboard input, /W is used to specify a number of seconds to wait. In other com- mands the number has other meanings and uses. See the description of the command for further details. NOTE: /Wnnnn is a general replacement for the old #nnnn notation. /W can and should be used wherever the # notation was previously valid. The # notation will disappear in future versions. /X provides eXtra functionality for a command. It has different meanings depending on the command being used. When getting keyboard input, /X specifies that extended keys will be accepted. /X also is used to specify hexadecimal output for the GET F (file size) command, and for other pur- poses with other commands. See GET F or the specific command for further details. GET.DOC SWITCHES Page 13 /~ is a temporary switch that is used with GET S only. Previously, if the user pressed Esc when you asked for a string, GET S would return 0 as if the user had not entered anything (i.e., just pressed Return). A more useful feature that has been suggested is for GET S to return the Environ- ment and ErrorLevel codes for the Escape surrogate. That way the program- mer can determine whether the user entered nothing or Escaped. The /~ switch, when used with GET S, will turn on this new feature. Page 14 Get User Input GET.DOC USING GET COMMANDS The description of GET commands is subdivided into the following sections of this manual. String Handling and Screen I/O DISK and FILE Information MEMORY and SYSTEM Information STRING HANDLING AND SCREEN I/O The commands C, N, S, Z, T, I, H, U, R, B, and V pertain to obtaining key- board input from the user, moving and modifying text strings, and getting and setting screen attributes. These commands take 0, 1, or 2 arguments as shown on the HELP SCREEN, and can make use of many of the switches. "prompt" refers to an arbitrary character string that will be displayed on the screen to coach the user as to what type of input is expected. If a prompt is used, it must be enclosed in double quotes. Prompts can be displayed in reverse video or in color with the /A switch. NOTE: The "prompt" can be used to issue ANSI.SYS screen control escape se- quences. It is more convenient to use GET to do this, than to make changes to the DOS PROMPT and have to reset PROMPT, especially if the BATch file is going to be run on various computer systems that may use different prompts. Do not use /A when you want ANSI.SYS or one of its clones to see the prompt. If any form of /A is specified, GET uses a different method of displaying the prompt which bypasses ANSI.SYS. Note also, that when /A is used, the maximum length of the prompt is 79 characters. Longer prompts will be truncated to 79 characters. Without /A the prompt can be longer, limited only by the maximum length of a BATch file line which in most versions of DOS is 128 characters. pattern is a special case of chars in which certain characters have spe- cial meanings. See the S command for detailed information. chars -- also see char information above -- are ASCII character strings which cannot include the space character, but may include surrogates. If any chars are given, user input will be limited to the characters in the character string including those indicated by the surrogates. If no chars are given, any key stroke will be accepted. To indicate that a carriage return, Esc, or space is acceptable, include the surrogate character listed above. CR and Esc will return 125 and 126 in the Er- rorLevel respectively, and the surrogate character in the Environment. Space will return 255 and Alt-255 if the characters are converted to up- percase. Uppercase is automatic with C, N, I, and T, or when the /U switch is used. It can be defeated with the /L switch. Think of ASCII 255 as an upper-case Space for purposes of GET input. Switches: /E specifies that Enhanced keyboard keys will be accepted. If you use /E, the BIOS function for the enhanced keyboard will be used. This permits the recognition of F11 and F12 as well as other enhanced and extended keyboard keys. /E should not be used unless you are sure that all users of your BATch file will be using enhanced keyboards because it absolute- ly does not work on machines with older BIOS's that do not recognize the enhanced keyboard interrupt. GET.DOC Get User Input Page 15 /X specifies that extended keys will be accepted. This has the same effect as the old surrogate for extended keys, "{", which has been retained (but see below) for compatibility. /X is used in the same manner as /E, but will not recognize F11, F12 or other enhanced keys. Example: GET C "Enter F1 to continue: " ƒ /X If extended or enhanced keyboard characters are specified with /X or /E (you don't need both) the scan code plus 100 will be in the ErrorLevel and the corresponding upper ASCII character in the Environment. A table of keyboard scan codes is included in the file SCANCODE.DOC. The extended and enhanced scan codes are mapped to the upper ASCII table by adding 100 to the scan code. For example, the scan code for F1 is 59. If extended keys are allowed, the upper ASCII character 159, "ƒ", will limit extended keystrokes to just the F1 key. Scan codes of 28 through 150 are recognized as the upper ASCII surrogates 128 through 250. A table of scan and ASCII codes is included in the file SCAN- CODE.DOC with the registered version. One method of entering the upper ASCII characters is by using the Alt-NumPad feature of DOS. There are some caveats that go along with this extended key scheme. 1. If you want extended and/or enhanced keys to be recognized, you must include either the old surrogate or the new switch for those keys. The switch is the preferred method as the surrogate will be discon- tinued in a future version. The upper ASCII characters will not be recognized as surrogates for the extended keys unless the switch or the surrogate is included. 2. If you use the old surrogate, it must come after all individual key specifications (if any) including the surrogates for CR and Esc. 3. If you specify any individual keys at all, then you must specify all keys that you want to allow. The following will not do what appears to be intended: GET C "Press x or any function key: " x /X In this example, only the X key will be accepted even though the /X switch is included. A better example is: GET C "Press x or F1: " xƒ /X or equivalently but not preferred: GET C "Press x or F1: " xƒ{ 4. Also note that the mapping of extended keys for GET U is not the same as for GET C. /C Break: The /C switch will suppress DOS Control-C and Ctrl-Break hand- ling. It applies only to the S, C, and N commands. Ctrl-Break handling works a bit differently according to whether you have specified a wait- ing time or not. If no timeout has been specified, Ctrl-Break will just cause a beep. If a timeout has been specified, and the first keystroke is Ctrl-Break, then GET will simulate a timeout with an ErrorLevel of 0, the same ErrorLevel you would check for to see if there was a timeout. If any character is entered, the timeout is cancelled, and Ctrl-Break is handled as if there is no timeout. For single character input, Ctrl-C will return the value and character 3 <''> if all characters are al- lowed (no chars string), or a beep if specific chars are specified. This provides versatility in break handling, but some experimentation would be a good idea to become familiar with the methods. Page 16 Get User Input GET.DOC /W[nnnn] The number nnnn following /W will be used to establish the number of seconds to wait for the first key stroke to be entered. If timeout takes place with nothing entered, the ErrorLevel will be 0, and there will be no GET variable in the Environment. If /W is omitted, GET will wait forever. If a wrong key is pressed the timeout is cancelled. Example: GET C "Answer Yes or No: " YN /W20 will wait 20 seconds for a character to be entered. If none are entered in that time, GET will exit with 0. If a wrong character (not Y or N) is entered, GET will wait until a correct character is entered regard- less of the time. The default if /W is omitted is interpreted to mean wait forever. NOTE: /W has the same effect as the old #num syntax, which is retained in this version for compatibility. Example(old method): GET C "Enter F1 to continue: " ƒ#20 /X Example(new method): GET C "Enter F1 to continue: " ƒ /X /W20 Caution, the old #nnn syntax will be eliminated in future versions. /W0 or /W with no number indicates no wait. The prompt will be displayed, and GET will immediately exit with ErrorLevel 0. This is useful to "echo" text in reverse video or in color with the /A switch. If a character is ready in the keyboard buffer due to a type-ahead, GET C, T, and N will read that character. If it was a valid character for the command, it will be reported as a valid character for the command. /L will convert any uppercase Environment characters to lowercase. For get C, T, and N, the ErrorLevel will still represent the ASCII code for the uppercase character, and the Echo, if any, will be the uppercase character. General: The C, N, I, and S commands read characters using a BIOS call so they bypass Standard Input and most keyboard redefinition methods (mac- ros). The old "surrogate" methods for Ctrl-Break, Extended, and En- hanced keys are supported in Release 2.5 for compatibility, but will not be supported in future versions. IMPORTANT: Please remember that the special ASCII characters '<', '>', and '|' are DOS redirection characters and you cannot use them as characters in BATch files. 4DOS also uses '^' and the grave accent (back quote) as special characters so they should not be used unless you know that no users of your BATch file will be running 4DOS or NDOS in- stead of COMMAND.COM. Single keystrokes for C, N or T are acted on without pressing Enter. (String input, of course, will require the user to press Enter.) When a character is entered by the user in response to C, N, or T, it is compared with the list of valid chars (if any). This validation of characters is not case sensitive. That is, if the user enters a lower- case letter it will be converted to uppercase and the chars will also be converted to uppercase if necessary before any validation comparisons are made. When checking for string matching with the MS DOS BATch IF subcommand, remember that it is case sensitive. Different versions of DOS handle IF "string1"=="string2" GET.DOC Get User Input Page 17 somewhat differently, and there have been several "bugs" reported in one version or another. Try to test any such constructs under several DOS versions including DR DOS and 4DOS/NDOS if possible. In some versions the string cannot contain any spaces. The test under 4DOS is not case sensitive, and it can contain spaces if the strings are enclosed in dou- ble quotation marks. Only 4DOS does it right. Page 18 GET Character GET C GET C Get Character Syntax: GET C[E] ["prompt"] [chars] [/switches] Input: "prompt" to be displayed. chars to specify the acceptable characters that can be entered. /switches - /A /W /C /M /E /X /V /L Output: ErrorLevel - ASCII or surrogate scan code. Environment - character C is short for "Character". GET C obtains a single character from the user and does not wait for a carriage return <CR> to be pressed. As soon as the user presses a key, GET immediately evaluates the key that was pressed. The keystroke will be echoed to the screen to provide the user with feedback on the key that was pressed. If the keystroke is an alphabetic character (letter) it will be converted to uppercase if necessary, although the echo will be the actual letter typed in by the user. The storage of the letter in uppercase can be reversed with the /L switch for lowercase. GET CE is a special case in which the character is not echoed to the screen. This might be useful if the character represents a password or other secret symbol that must be held confidential and hidden from the eyes of casual observers, or if the character entered has no special significance as with the PAUSE command. In its simplest form, GET C, no prompt is issued and any keystroke except extended keys will be accepted. The BATch file will simply pause until a key is pressed. However, the user should be given some indication of what is expected, and the prompt provides a convenient means to do so. For example, you can emulate the DOS PAUSE subcommand with the following command. GET C "Press a key when ready . . ." This is more convenient than the PAUSE subcommand because the prompt can be anything you want it to be such as "Press a key when you want to con- tinue . . .". As with the PAUSE command, it can be preceded in the BATch file with ECHO statements giving more information as to what the pause is for. It is also more useful with the /A switch to control the attribute, and/or the /W switch to control the pausing time. The optional argument [chars] is a single string of characters that limit the acceptable user input. Any other character entered will produce a beep, and GET will wait for another character. In addition to the com- mon alphanumeric keyboard characters, special characters can be indi- cated as discussed above under Surrogates and Extended Characters. If the /C switch is included, the user will not be able to exit by pressing Ctrl-Break, and Ctrl-C will be treated like any other character; i.e. if any chars are specified, then Ctrl-C will not be allowed because it can- not be specified, but if no chars are specified then Ctrl-C will return ASCII 3. Ctrl-C is ASCII 3 and will be indicated by the number 3 in the ErrorLevel and the ASCII character for 3, the heart, in the Environment. EXAMPLES: 1. To issue a message and wait for a key to be pressed similar to the DOS PAUSE subcommand: GET C GET Character Page 19 ECHO Make sure your printer is turned on. GET C "Press a key when ready . . ." 2. To present a simple menu and let the user make a selection. The /C switch indicates suppression of the Control-Break keystroke. Neither Control-C nor Control-Break will be accepted. :MENU ECHO A Word Processor ECHO B Spreadsheet ECHO C Database GET C "Select A, B, or C: " ABC /C IF "%GET%"=="A" GOTO WP IF "%GET%"=="B" GOTO SS IF "%GET%"=="C" GOTO DB GOTO MENU :WP Rem Call your word processor here GOTO MENU :SS Rem Call your spread sheet here GOTO MENU :DB Rem Call your database manager here GOTO MENU 3. To illustrate the use of surrogates. The empty space between } and ~ is the ASCII 255 character entered with Alt-255, not the regular space character. The /W20 waits 20 seconds for a response. /A will cause the prompt to be displayed in reverse video. :START GET C "Press <CR>, space bar, or Esc: " } ~ /W20 /A IF ErrorLevel 255 GOTO SPACE IF ErrorLevel 126 GOTO ESCAPE IF ErrorLevel 125 GOTO RETURN GOTO START :SPACE Echo The space bar was pressed. GOTO END :ESCAPE Echo The Escape key was pressed. GOTO END :RETURN Echo The Enter key was pressed. :END 4. Same example as 3 using the Environment variable instead of the Error- Level. Note that " " is ASCII 255 in double quotes, not the regular space character. As above, the /W20 switch will wait for 20 seconds then continue, but since none of the valid characters will be in the %GET% variable, the next 3 lines will fall through and the GOTO START line will cause a loop back to :START for another 20 second wait. Page 20 GET Character GET C :START GET C "Press <CR>, space bar, or Esc: " } ~ /W20 IF "%GET%"==" " GOTO SPACE IF "%GET%"=="~" GOTO ESCAPE IF "%GET%"=="}" GOTO RETURN GOTO START :SPACE Echo The space bar was pressed. GOTO END :ESCAPE Echo The Escape key was pressed. GOTO END :RETURN Echo The Enter key was pressed. :END GET N GET yes/no aNswer Page 21 GET N Get yes/no aNswer Syntax: GET N[E] ["prompt"] [/switches] Input: "prompt" to be displayed. /switches - /A /W /C /M /V /L Output: ErrorLevel - ASCII or surrogate code. Environment - character GET N is a special case of C that will accept only y, n, carriage return, or Esc. The Ctrl-C suppression and the number of seconds switches to wait may be specified, but no [chars] argument will be recognized. The syntax rules for GET C apply to GET N. The only purpose for GET N is just to make programming yes/no answers a bit simpler than using GET C and having to always specify the YN and surrogate characters. EXAMPLES: 1. The following two statements are functionally identical: GET N "Answer yes or no (y/n): " GET C "Answer yes or no (y/n): " YN}~ 2. Using ErrorLevel. 89 is the ASCII code for Y, 78 is the ASCII code for N, 125 is the code for Carriage Return, and 126 for Escape. A method of using the Environment for defining variables is illustrated. GET N "Answer yes or no (y/n): " IF ErrorLevel 126 GOTO ESCAPE IF ErrorLevel 125 GOTO RETURN IF ErrorLevel 89 GOTO YES IF ErrorLevel 78 GOTO NO SET GET=Break GOTO END :ESCAPE SET GET=Escape GOTO END :RETURN SET GET=Return GOTO END :YES :NO :END Echo The %GET% key was pressed. 3. Same example as 2. This time the Environment is used instead of the ErrorLevel. Since we are not using Control-C suppression, it is pos- sible to break out of the BATch file with Control-C or Control-Break in this and the previous example. Remember that in many versions of DOS the IF subcommand is case sensitive. GET N converts all alphabetic charac- ters to uppercase, so always use uppercase comparison unless you are using the /L switch. Page 22 GET yes/no aNswer GET N GET N "Answer yes or no (y/n): " IF "%GET%"=="~" GOTO ESCAPE IF "%GET%"=="}" GOTO RETURN IF "%GET%"=="Y" GOTO YES IF "%GET%"=="N" GOTO NO SET GET=Break GOTO END :ESCAPE SET GET=Escape GOTO END :RETURN SET GET=Return GOTO END :YES Put your code for Yes on lines after this label. GOTO END :NO Put your code for No on lines after this label. :END Echo The %GET% key was pressed. GET T Moving Text Page 23 GET T Moving Text Syntax: GET T[E] "filespec" [chars] [/switches] Input: file specification containing moving text to be displayed. chars to specify the acceptable characters that can be entered. /switches - /M /V /L Output: ErrorLevel - ASCII or surrogate scan code. Environment - character GET T is another special case of GET C which provides a special effect. The prompt information is presented as a moving line of text across the bottom of the screen. This permits having prompt strings up to 4096 characters long, and the motion of the characters helps to catch the users attention. T requires a file with the prompt string which will be displayed moving across the bottom line of the screen. Currently only standard 25 line screens are supported. The text file should be plain ASCII without any control characters (No CR, LF, or any other characters below ASCII 32). To be effective the prompt must be over 80 or more characters long, and to ensure smooth wrap-around the first 79 charac- ters should be repeated at the end. The maximum length for the text of the moving prompt is 4096 characters. Over that it will be truncated. T does not accept a number of seconds-to-wait argument at this time so it will wait until a valid key is pressed. The T command can fail with an "Invalid Command" message if the file is not properly specified and cannot be found, or if the prompt string is less than 80 characters. An ErrorLevel of zero should be tested to determine if the command was successful (see example 2 below). A prompt string of exactly 80 characters will remain stationary. The question has been asked as to how to go about creating such a long prompt string without carriage returns or other control characters. Many text editors have the capability to do this by turning off word wrap. A good text editor will let you do just about anything you want to do with ASCII text. Most programmers use a text editor instead of a word processor while creating and editing their code. Many word pro- cessors will let you use them as text editors by specifying "non- document" mode as appropriate. As with many things related to program- ming, trial and error experimentation is often the order of the day. Sometimes it is called "hacking". EXAMPLES: 1. If there is a file on the GET disk named SAMPLE.TXT, enter the follow- ing command to see the moving text effect: GET T "SAMPLE.TXT" 2. Example 2 for GET C can easily be modified to use a moving text prompt by changing GET C to GET T and replacing the prompt with the filename as follows. The timeout option is not effective with GET T. Page 24 Moving Text GET T :START GET T "sample.txt" } ~ IF NOT ErrorLevel 1 GOTO END IF ErrorLevel 255 GOTO SPACE IF ErrorLevel 126 GOTO ESCAPE IF ErrorLevel 125 GOTO RETURN GOTO START :SPACE Echo The space bar was pressed. GOTO END :ESCAPE Echo The Escape key was pressed. GOTO END :RETURN Echo The Enter key was pressed. :END In this example note the addition of the line IF NOT ErrorLevel 1 GOTO END. If the named file is not found due to not being in the current directory, or not having the correct path or name specified, then GET will report "Invalid Command" and exit with ErrorLevel 0. The added statement is a check for ErrorLevel equal 0, and should always be in- cluded when using the GET T command. You may include drive and path with the filename, but GET must be able to find it where it is specified to be. GET S GET String Page 25 GET S Get String Syntax: GET S[E] ["prompt"] [pattern] [/switches] Input: "prompt" to be displayed. pattern to control character entry /switches - /A /W /C /M /V /U /~ /L Output: ErrorLevel - length of string entered. Environment - string. S accepts character string input terminated by a carriage return. SE is the same but does not echo user input to the screen. The latter is use- ful for hiding the entry of a password, for example. Extended and en- hanced keys will not be accepted, but break can be suppressed with /C. The length of the string entered is returned in ErrorLevel. If the user presses Esc, GET will exit with 0 in ErrorLevel as if a timeout has oc- curred unless the /~ switch is specified as described below. As with GET C, the prompt will be issued and then GET will wait with the cursor on the same line as the prompt for keyboard input. If a /W is specified, GET will wait the specified number of seconds for the first key to be pressed, then exit with an ErrorLevel of 0 if no key has been pressed. If any key is pressed during the waiting period, the wait is cancelled and GET waits for the user to press the Carriage Return (En- ter) key. The /~ switch modifies the result if Escape is pressed. If the Escape ac- tion switch is specified as /~, when Esc is pressed GET will exit and leave the Esc surrogate <~> in the Environment and 126 in ErrorLevel. This permits testing whether it was in fact a timeout or if the user pressed the Escape key. The /~ switch is needed as a compatibility fea- ture. Without it, GET S will work as it did in Release 2.2. The length of a string for the S command can be controlled by creating a pattern of characters equal in number to the maximum length of the string allowed. If the argument is omitted the default is 79 charac- ters. A beep will be sounded if the maximum length has been reached and more characters are attempted, or if any characters do not match the specified pattern. The pattern in the argument specifies the acceptable characters for each position as follows. Note that the uppercase characters T, A, and Z will cause lowercase characters to be converted to uppercase. Conver- sions to uppercase will also cause the space character to be converted to ASCII 255. This will facilitate BATch file checking with the IF sub- command. tT - any typeable character, T - a-z will be uppercased. aA - any alphabetic character, A - a-z will be uppercased. zZ - any alphanumeric character, Z - a-z will be uppercased. 9 - any digit 0-9. Alt-255 - space character only. Any other character must match the character entered exactly. In a sense you can think of Alt-255 as an uppercase space character. Re- member that the regular ASCII space is used as a delimiter so the scan- ning of the pattern stops if an embedded space is encountered. If you need to specify the space, use the surrogate Alt-255, otherwise use t or T if a space is permitted. If you are going to test the input with the DOS IF subcommand use Alt-255 or T. This will cause the space to be converted to an Alt-255 which can be tested. Unless you are using 4DOS, Page 26 GET String GET S if you try to test a string which contains a space with IF, you will get the message "Bad command or file name", even with MS DOS 5.0. This is because COMMAND.COM stops parsing the string when it encounters a space which it considers to be a delimiter even if it is enclosed in quotes. EXAMPLES: 1. The following example lets the user type in any characters up to a limit of 79. The string that is typed in will be in the Environment, and the length of the string in the ErrorLevel. Because the /~ switch is used, if the user presses Esc, the Escape surrogate "~" will be in the Environment and 126 in the ErrorLevel. If the user presses Ctrl-C or Ctrl-Break, DOS will break out of GET with no change to the GET vari- able in the environment, and an undefined value in the ErrorLevel, pos- sibly 3 for Ctrl-C.. For this reason it is a good idea to clear the GET variable with the statement SET GET= before issuing the GET S command, or use /C to suppress Ctrl-Break as in the next example. The /U switch causes lowercase characters in the string to be converted to uppercase to facilitate IF tests. GET S /U /~ 2. This example asks the user for a password. It does not echo the entry to the screen to keep the password secure from prying eyes. It sup- presses Ctrl-Break but allows the BATch file to check to see if the user entered Escape. The password is limited to 8 alphabetic or numeric characters, and all alpha characters will be converted to uppercase to facilitate testing. The /a switch causes the error message to be dis- played in reverse video, and the /w switch causes GET to immediately exit after displaying the prompt. :START GET SE "Enter your password: " ZZZZZZZZ /C /~ if "%GET%"=="~" goto Escape if "%GET%"=="PASSWORD" goto PWOK Rem Display error message in reverse video GET C "Incorrect Password" /a /w goto START :Escape GET N "Do you want to cancel your logon? " if NOT "%GET%"=="Y" goto START Echo Your logon is cancelled. goto EXIT :PWOK Echo Your logon has been accepted Rem Do whatever is necessary here to complete the logon. :EXIT 3. The next example gives the user 30 seconds to respond. If there is no first name entered within 30 seconds, GET will beep and the BATch file will cycle back to :START and ask the question again. If there is a timeout on last name, the BATch file will report that the session is cancelled and exit. Only alphabetic characters are allowed, and the first character will be automatically capitalized. GET S GET String Page 27 :START GET S "Enter your first name " Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa /W30 if NOT ErrorLevel 1 goto START SET FIRST=%GET% GET S "Enter your last name " Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa /W30 if errorlevel 1 goto NAME Echo Your session is cancelled. Rem Do whatever is necessary to cancel session here. goto EXIT :NAME Echo Your name is %FIRST% %GET% :EXIT Page 28 Check Key Buffer GET I GET I Check Key Buffer Syntax: GET I[E] "prompt" [/switches] Input: "prompt" to be displayed. /switches - /A /M /V /E /X Output: ErrorLevel - ASCII or surrogate scan code. Environment - character I checks to see whether a key has been pressed but it does not wait for a keystroke if none is in the buffer; i.e. if the user has not pressed a key in type-ahead mode. The character that is waiting will be reported in the same manner as for GET C, but it will remain in the keyboard buffer. If there is no character waiting, the ErrorLevel will be 0 and GET or the variable specified with /V will be expunged from the Environ- ment. IE will read the key if it is present and report it in the same manner as C, or return 0 and expunge GET from the Environment if no character is waiting. The difference in the IE command from the C command is that IE does not wait if no key is waiting. If you specify a zero waiting time for GET C with GET C /W or GET C /W0 it will be functionally equivalent to GET IE. You can control whether Extended or Enhanced keys are to be included in the same manner as for GET C. A prompt can be included and will be dis- played, which makes I useful to "echo" text to the screen like the DOS ECHO command, but with GET you can specify reverse video or color at- tributes. One way to make use of GET I is to allow a key to be pressed during boot- up (or while any BATch file is running for that matter), then check to see if a key has been pressed and take action accordingly, but if no key was pressed there will be no delay. Another use would be in a BATch program that the user is familiar enough with that s/he may anticipate the next question. GET I could be used to check to see if the user has answered the question before it was asked. EXAMPLES: 1. In these examples a GET command (GET U), explained elsewhere, is used to place a key in the keyboard buffer, then GET I checks to see if it is there. In this first example, the letter "a" is placed in the buffer and GET I reports that "A" is waiting with ErrorLevel 65 and GET=A. The character "a" will remain in the buffer and will be available to the next program that reads keyboard input. In this case, neither extended nor enhanced keys will be seen. Rem Simulate user pressing the "a" key. GET U "a" Rem Check to see if the key is in the buffer. GET I if ErrorLevel 1 goto ISTHERE Echo There is no key in the buffer. goto EXIT :ISTHERE Echo The key in the buffer is %GET%. :EXIT Rem Note that if you run this BATch file from the command line, you will Rem see "a" at the next DOS prompt when DOS reads the keyboard buffer. GET I Check Key Buffer Page 29 2. Clearing the keyboard buffer. By using the switch /E, both extended and enhanced keys will be seen as well as all standard keys. Do not use /E unless you know that all users will have enhanced keyboards. Note: This example is for illustration only. A faster method of clearing the buffer is to use the /B switch. :LOOP GET IE /E if ErrorLevel 1 goto LOOP 3. Suppose you would like to be able to do a clean boot without any TSR's when you want to run a program such as a disk defragmenter. You can have GET I check if you have pressed a key, and skip your TSR's in your AUTOEXEC.BAT if you have. GET IE if ErrorLevel 1 goto CONTINUE Rem Load first TSR here. Rem Load Second TSR here. Rem ... Rem Load Last TSR here. :CONTINUE with the rest of your AUTOEXEC.BAT Page 30 Put String (Zap) GET Z GET Z Put String (Zap) Syntax: GET Z "string" [skip] [/switches] Input: "string" to be placed in the Environment /switches - /M /V /U /L /W Output: ErrorLevel - length of string. Environment - string Z uses the "string" as input. It will put the string into the Environment as the value of the GET= or /Vvar= variable. If you include the /M switch, GET will attempt to bypass any secondary environments and put the string in the master Environment. By "master Environment" is meant the environment of the original command processor that was loaded when you started your computer, as contrasted with what we shall call the "current" Environment defined as that of the command processor that is running the BATch file. The current Environment will be the same as the master Environment unless a secondary command processor has been in- voked. If GET is running under a secondary command processor, GET Z with /M will attempt to bypass the current Environment of the secondary com- mand processor and find the master environment. In the latter case, the GET variable will not be available to the current BATch file. See dis- cussion of Environment and Shells. If a numerical [skip] argument is specified, it will be taken to specify the number of characters to skip over before transferring the remainder of the string to the environment. The /W switch can be used to specify the maximum length of the string as described for GET ZE below. Thus, GET Z can be used to extract a substring from "string" starting with the character after skip and using up to the number of characters specified by /Wnnnn. If [skip] is omitted the default is 0 meaning to start at the beginning of the string. NOTE: The use of /W with GET Z and GET ZE is different from the use with other input commands where it denotes a time to wait for input. GET Z can have several uses. A few that come to mind are: uppercase a string to test it with the IF subcommand, measure the length of a string, count the number of times through a loop by measuring the length of a string that has a character concatenated on each pass, fill out a string to a fixed length by concatenating blanks and measuring its length, extract a substring from a string. EXAMPLES: 1. Place a string in the master Environment. The master Environment will then contain "GET=This is the string" and the ErrorLevel will be the length of the string (18). To verify that the string was placed in the master Environment, first run a secondary command processor by typing COMMAND at the DOS prompt. Then run this example and see that the string is not in the current environment by entering SET and viewing the Environment. Finally, enter EXIT to return to the original command pro- cessor and enter SET again to see that the string is actually in the master Environment. GET Z "This is the string" /M 2. Suppose you want to fill out a string with blanks to reach a certain fixed length. In this example let the fixed length be 16. This is one way to implement a loop and control the number of times the loop occurs. You can either right justify or left justify, and you can append spaces, unlike using the DOS SET command. GET Z Put String (Zap) Page 31 Rem Get user input, maximum of 16 characters. get s "Enter name: " tttttttttttttttt /a :FILL If less than 16 characters entered, fill with blanks. if ErrorLevel 16 goto LENOK Rem Append a blank and loop back to check if enough get z "%GET% " goto FILL :LENOK Now we have the length we want. Echo "The string is %GET%" 3. Use GET Z to extract the 3rd, 4th, and 5th characters from a string. Rem Turn on GET's reporting feature SET GET?=ON GET Z "abcdef" 2 /w3 The Environment is: cde The ErrorLevel is: 3 4. Suppose there is an Environment variable named VER and that in this case it has the value VER=3.31. We can extract the DOS minor version with GET Z as follows. GET Z "%VER%" 2 The Environment is: 31 The ErrorLevel is: 2 5. Use GET Z to make sure an environment string is in uppercase to facili- tate testing it with the BATch IF subcommand. Spaces will be converted to ASCII-255 otherwise the DOS IF test would fail. Remember to use ASCII-255 for the test in your BATch file if there are any spaces. Let "varname" be the name of a variable in the Environment. GET Z "%varname%" /U /Vvarname= Rem In the next line, the "space" between B and S is really ASCII-255. IF "%varname%"=="BOB STEPHAN" goto NAMEOK Echo The name did not match goto END :NAMEOK Echo The name matched :END Page 32 Standard Input GET ZE GET ZE Standard Input Syntax: GET ZE "prompt" [/switches] Input: "prompt" to be displayed. /switches - /A /M /V /U /W /L Output: ErrorLevel - length of string. Environment - string. ZE will take input from Standard Input and transfer it to the GET= or /Vvar= variable in the Environment. The input must be less than 80 characters and must be terminated with a carriage return. ZE will take input from the keyboard (Get String), or from redirection or piping. If you specify a prompt for ZE, it will be displayed before reading stan- dard input. GET ZE works similar to GET S, but uses DOS to obtain the input string from the user; therefore, it is not able to monitor each keystroke and will not be able to suppress Ctrl-Break with the /C switch. You can force the string to uppercase with the /U switch, or to lowercase with the /L switch. /W can be used with both GET Z and GET ZE to specify the maximum length of the string. If the input string is longer than the maximum specified with /W, it will be truncated to the length specified. EXAMPLES: 1. GET S uses the BIOS interrupt to get characters from the user, but you can also use DOS Standard Input with GET ZE. The prompt will be dis- played and the string can be entered from the keyboard for a maximum of 79 characters. The /U switch can be used to force the environment vari- able to uppercase, but the user will see it just as it was typed in. GET ZE "Enter a string: " /U 2. You can use GET ZE to pipe the current directory into the current En- vironment by using DOS piping. This could be used to redirect any stan- dard output into an Environment variable. Of course, GET Y is the preferred method of putting the current directory into the Environment with GET, but this illustrates the method to do it with any program that writes to standard output. In some cases piping CD into GET ZE might be preferable because CD includes the drive specification. CD|GET ZE The Environment is: D:\QPRO The ErrorLevel is: 7 3. You can read the first line of a text file. If you don't want to see the echo from DOS, redirect the output to NUL. The general syntax is GET ZE<filespec>NUL. In this example, the output from the DOS DATE com- mand is redirected to a file, then read in to the Environment with GET ZE, and finally the day of the week is extracted with GET Z. NOTE: The date could also have been piped directly into GET as in the previous ex- ample, but for the purposes of this example an intermediate file is used. GET ZE Standard Input Page 33 Rem Stack <return> to automate the DATE command. get u 13 Rem Use the DOS DATE command to create a file for the date date >date.txt Rem The first line of the file will have the format Rem Current date is Sun 11-17-1991 Rem Read the first line into the variable GET=. get ze <date.txt Rem Extract the day of the week in characters 17-19 get z "%GET%" 16 /w3 Rem The Environment will now contain the variable GET=Sun. Rem Rem NOTE: Different versions of DOS have different formats Rem for the output of the DATE command. Rem Rem Now erase the temporary file. del date.txt Page 34 'Rithmetic GET.DOC GET R 'Rithmetic Syntax: GET R[E] num1 [/Wnum2] [/switches] Input: one or two numbers, maximum of 4 digits each. /switches - /M /V /W Output: ErrorLevel - num1+num2, RE - num1-num2 Environment - same as ErrorLevel R for 'Rithmetic adds or subtracts two numbers. GET R adds the two numbers GET RE subtracts the second from the first The arithmetic result is in both the Environment and ErrorLevel. If only one number is given, the other number defaults to 0. The max number of digits for each number is 4. Thus a character representation of a number can be converted to a number in the ErrorLevel. See examples below for information about results larger than 255 or negative. EXAMPLES: 1. Convert a numerical Environment variable to an ErrorLevel. Suppose the following string is in the Environment: VAR=45. Then GET R %VAR% will set the ErrorLevel to 45, and place GET=45 in the Environment. 2. Suppose you need to set up a loop in a BATch file. You can do it this way. SET COUNT=0 :LOOP GET R %COUNT% /W1 /VCOUNT= Echo The count is %COUNT% IF NOT ERRORLEVEL 10 GOTO LOOP 3. You can use GET R to pass a return code from a CALLed BATch file to its parent. Of course, this could have been done by SETting and Environe- ment variable, but with GET R you can use the ErrorLevel if you want. Echo This is the child batch file. Rem Set the default ErrorLevel to 0, suppress Environment variable. GET R 0 /V- Rem Now make tests and set ErrorLevel accordingly. If "%COMSPEC%"=="C:\COMMAND.COM" get r 1 /V- If "%COMSPEC%"=="C:\4DOS.COM" get r 4 /V- @Echo off Rem This is the parent file. CALL CHILD If ErrorLevel 4 Echo 4DOS is loaded. If ErrorLevel 1 Echo COMMAND.COM is loaded. If Not ErrorLevel 1 Echo Unknown command processor. 4. If the result is greater than 255, the ErrorLevel is modulo 256. For example: 256=0, 257=1, ..., 511=255, 512=0, etc. set GET?=on GET.DOC 'Rithmetic Page 35 GET R 195 /W350 The Environment is: 545 The ErrorLevel is: 33 5. GET uses simple computer integer arithmetic. Negative numbers are not recognized as such. If a larger number is subtracted from smaller, the result is 65536 minus the absolute value of the difference. GET RE 10 /W20 The ErrorLevel is 246 The Environment is 65526 Page 36 Clear (Blank) Screen GET B GET B Clear (Blank) Screen Syntax: GET B[E] [New attribute] [/switches] Input: desired new attribute in decimal for B, hex for BE. /switches /M /V Output: ErrorLevel - old attribute (decimal of course). Environment - old attribute in decimal, hex for BE. B the screen Blanker actually performs a clear screen, not a true blank- ing which leave the screen display intact but merely hides it. By doing so, it is able to control the screen attribute (color). GET B uses your color settings unless you give it a different attribute to use. It automatically adapts to any number of lines on the screen (e.g. EGA 43 or VGA 50). If an attribute argument is given it is taken to be a 1, 2, or 3-digit decimal number that is converted to a two-digit hexadecimal number for the attribute. The same table of colors and attributes that is used for the /A switch is used for the GET B command. BE regards an argument as a 1 or 2-digit hex number, and the GET value in the Environment is in hex. EXAMPLES: 1. Do a simple ClearScreen (CLS) without changing colors or number of lines. Suppose the old attribute was black and white. Rem Turn on GET reporting feature SET GET?=ON GET B The Environment is: 7 The ErrorLevel is: 7 2. Set color to blue background with white text. Save the old attribute in the environment variable ATTR. GET B 23 /VATTR= The Environment is: 7 The ErrorLevel is: 7 3. Restore the saved attribute. GET B %ATTR% The Environment is: 23 The ErrorLevel is: 23 Rem Turn off GET reporting feature SET GET?= GET V Get/set video mode Page 37 GET V Get/set video mode Syntax: GET V[E] [New mode/color] [/switches] Input: optional new video mode for V or color for VE. /switches /M /V Output: ErrorLevel - old mode or color Environment - old mode or color V reports and optionally sets the video mode. Don't change Video mode un- less you have a specific reason for doing so to prevent setting a mode that is not supported by the system running the BATch file. The following Video Display Mode table is excerpted from "The New Peter Norton Programmer's Guide to The IBM PC & PS/2," page 72. Mode # Type Resolution Colors Video Subsystem 0, 1 Text 40 x 25 16 CGA, EGA, MCGA, VGA 2, 3 Text 80 x 25 16 CGA, EGA, MCGA, VGA 4, 5 Graphics 320 x 200 4 CGA, EGA, MCGA, VGA 6 Graphics 640 x 200 2 CGA, EGA, MCGA, VGA 7 Text 80 x 25 Mono CGA, EGA, MCGA, VGA 8, 9, 10 PCjr only 11, 12 Used internally 13 Graphics 320 x 200 16 EGA, VGA 14 Graphics 640 x 200 16 EGA, VGA 15 Graphics 640 x 350 Mono EGA, VGA 16 Graphics 640 x 350 16 EGA, VGA 17 Graphics 640 x 480 2 MCGA, VGA 18 Graphics 640 x 480 16 VGA 19 Graphics 320 x 200 25 MCGA, VGA EXAMPLES: 1. Get the current video mode and save it in the variable VIDEO. Change to video mode 2. Later restore the original mode. GET V 2 /vvideo= Rem Do what you need to with mode 2 Rem Restore original mode GET V %VIDEO% Rem Clear out VIDEO variable SET VIDEO= 2. Suppose you have an "ill behaved" program such as a game that leaves the video in a graphics mode when it exits. You can save the orginal mode before executing the game, then restore it later. Rem Store original video mode GET V /vvideo= Rem Run the ill behaved game GAME Rem Restore original mode GET V %VIDEO% Rem Clear out VIDEO variable SET VIDEO= Page 38 Get/set video border GET VE GET VE Get/set video border VE will get/set the border color on a VGA or EGA monitor. See the color table below. One interesting use is to set different border colors for each of your DESQview windows if you are a DV user. GET VE will take any of the 8 basic color codes 0-7. The additional combinations that can be used for /A or GET B have no meaning for GET VE. The color codes are: 0 Black 2 Green 4 Red 6 Brown 1 Blue 3 Cyan 5 Magenta 7 White EXAMPLES: 1. Set the border color to red. It was black. Rem Turn on GET reporting feature SET GET?=ON GET VE 4 The Environment is: 0 The ErrorLevel is: 0 Rem Turn off GET reporting feature SET GET?= GET H Date and Time Page 39 GET H Date and Time Syntax: GET H[E] code [/switches] Input: Code from the table below /switches /M /V Output: ErrorLevel - Environment - H The H Date and Time command works differently than most of the others. The value to be obtained is determined by a coded numerical argument. The codes are as follows with 1 being the default. 1 Day of the Week - Sunday=0 16 Hour 2 Day of the Month 32 Minute 4 Month - January=1 64 Second 8 Year 128 Odd or Even (H only) For H, only one value is returned for each call of GET. The Environment will contain the character representation of the ErrorLevel, except for Year, or for the Odd/Even feature, or if no code is given. Since Error- Level has a maximum of 255, only the last two digits of the year will be reported, but the Environment will have the full value. If no code is given, the ErrorLevel will contain the default Day of the Week but no Environment variable will be created. The Odd/Even feature is obtained by adding 128 to the desired code. The Environment will contain the value for the code, but the ErrorLevel will be 1 if the value is odd or 0 if it is even. This provides a means to alternate doing something like running COMPRESS on C: on even days and D: on odd days. A code of 128 by itself will put the odd or even in- dicator for the Day of the Week in the ErrorLevel but no Environment variable will be created. HE will place a concatenated string in the environment. You can "build your own" string. HE requires that you add up the codes for the values you want concatenated. With this form of the command the ErrorLevel is the length of the GET variable, but it is not very meaningful or useful. 128 does nothing for HE either. If you can find a use for it with HE, you can include a "prompt" string in double quotes. The Environment variable will contain the prompt string with the requested date and/or time information concatenated. EXAMPLES: 1. This is a rather elaborate BATch file that can be called to provide a formatted date. Call it SHOWDATE.BAT. When you call SHOWDATE it will report something like "The date is August 25, 1991". This information could just as easily be stored as an Environment variable for use by other BATch files and programs. Page 40 Date and Time GET H @Echo Off GET H 4 If "%GET%"=="12" set MONTH=December If "%GET%"=="11" set MONTH=November If "%GET%"=="10" set MONTH=October If "%GET%"=="9" set MONTH=September If "%GET%"=="8" set MONTH=August If "%GET%"=="7" set MONTH=July If "%GET%"=="6" set MONTH=June If "%GET%"=="5" set MONTH=May If "%GET%"=="4" set MONTH=April If "%GET%"=="3" set MONTH=March If "%GET%"=="2" set MONTH=February If "%GET%"=="1" set MONTH=January Get H 2 /VDAY= Get H 8 /VYR= Echo The date is %MONTH% %DAY%, %YR% 2. A GET BATch file can easily be set up to wait until a given time by using the H feature. In this example the first pair of GET calls checks every 15 minutes for the hour you want to wait until - in this case 11 p.m. or 23 in computer parlance. The next pair of GET calls checks the time once a minute and waits until the minute is 30. The BATch file will continue executing at 11:30 p.m. or shortly thereafter. @echo off :HOUR Check the hour every 15 minutes. GET C /W900 GET H 16 if not "%GET%"=="23" goto HOUR :MINUTE Check the minute every 60 seconds. GET C /W60 GET H 32 if not ErrorLevel 30 goto MINUTE Rem The BATch file will continue here at 11:30 p.m. 3. The above BATch file can be parameterized so it can be called with the hour and minute that you want it to wait until. Name this BATch file WAITFOR.BAT, then at the DOS prompt enter WAITFOR hour minute. For ex- ample, WAITFOR 23 30. A BATch file like this can be run in a DESQview window in the background and produce an alarm at a given time, or ex- ecute a program in the background or when the computer is unattended. It can easily be tuned down to the minute, or even the second by how fine you make the checkpoint intervals. @echo off :HOUR Check the hour every 15 minutes. GET C /W900 GET H 16 if not "%GET%"=="%1" goto HOUR :MINUTE Check the minute every 60 seconds. GET C /W60 GET H 32 if not ErrorLevel %2 goto MINUTE Rem The BATch file will continue here at the hour and minute you specify. Rem Sound your alarm, or do whatever here, for example, Echo ^G ^G ^G ^G ^G GET H Date and Time Page 41 4. Here are some BATch statements I use in my AUTOEXEC.BAT to do some things only once a day, such as run DOS 5.0 MIRROR to save a copy of my system information in case of a crash. The current date is saved on disk in a BATch file named SETDATE.BAT. It contains one line, for exam- ple: SET DATE=29. When I CALL SETDATE it stores the last saved date in the Environment as the DATE= variable. Then I use GET to get today's date and compare it with %DATE%. If they compare, I know that I have already done my once-a-day procedures and can skip them this time. If they don't compare, a new SETDATE.BAT is automatically created, and the once-a-day statements are executed. Follow it through here: Rem Call SETDATE to store the last saved date in the Environment CALL SETDATE Rem Get today's date to compare with. GET H 2 Rem Compare the last saved date with today's date. IF "%DATE%"=="%GET%" GOTO DATEOK Rem If false, recreate SETDATE with today's date. ECHO SET DATE=%GET% >SETDATE.BAT Rem Do your once-a-day procedures here; for example ... MIRROR D: E: F: Rem If the dates compared we would skip the above lines Rem thus speeding up succeeding boots. DATEOK: Rem Continue with your AUTOEXEC.BAT here. Rem Run MIRROR on your boot drive and load delete tracking for all drives MIRROR C: /TC /TD /TE /TF 5. HE was designed to produce output in the same form required by the DOS DATE and TIME commands. For example, if you need to temporarily change the system date (or time) and later restore it, you can do it with the following BATch file. @Echo off Rem HE 14 will report mm-dd-yy in the Environment: 14=2+4+8. get HE 14 /VDATE= Rem Now set the date as you need it for whatever reason, for example: DATE 6-15-90 Rem Now run the program that requires the new date. Rem . . . Rem Now restore the original date. DATE %DATE% Rem Clear out the DATE variable (unless you want to save it to use again). SET DATE= 6. Concatenate a "prompt" string with the date. Rem Turn on the GET reporting feature SET GET?=ON GET HE "The date is" 14 The Environment is: The date is 8-29-91 The ErrorLevel is: 20 Rem Turn off the reporting feature SET GET?= Page 42 Keyboard BUffer GET U GET U Keyboard BUffer Syntax: GET U "chars" num /Wnum [/switches] Input: characters and key codes to place in key buffer /switches /M /V /W /B Output: ErrorLevel - Number of characters actually stacked Environment - Not used, GET or /V variable will be cleared out. U will stack keys in the keyboard bUffer. The syntax is GET U "chars" num /Wnum where chars are any ASCII characters you want stacked in dou- ble quotes, and the "num"s are decimal representations of values for ei- ther ASCII codes or scan codes. Up to 4 digits can be used for either number. E.g. to end the string with a carriage return use 13 or /W13. To enter a scan code add it to 255. Note that this is purposely dif- ferent from the scan code surrogates for the GET C command. NOTE: GET U will only work on PC/XT's with BIOS dated 01/10/86 and later, PC/AT's with BIOS dated 11/15/85 and later, and PS/2s! With GET U you can provide a default entry for a GET S string; however, the DOS keyboard buffer only holds 15 characters, so it has to be rather short. Use GET U "default" followed by GET S "prompt", and the default string will be entered for the user. The user can either change it by backspacing or accept it by pressing enter. The ErrorLevel will contain the number of characters or codes actually placed in the buffer. If the buffer fills up before all the characters or codes are stacked, GET will beep and exit. By testing the ErrorLevel for the number of characters and codes, you can tell if the stacking was successful. To make the full buffer available, the /B switch can be used to clear the buffer. EXAMPLES 1. The following will stack the word "help" in the buffer and execute it as a command by also stacking the Enter key (ASCII 13 for CR). To make the stacked command execute, the BATch file must exit to activate the DOS prompt. GET U "help" 13 /B Rem Test that 5 characters were stacked if ErrorLevel 5 goto EXIT Rem Not all characters were stacked, so clear the buffer and exit GET I /B :EXIT 2. The scan code for F1 is decimal 59 so use 314 (=59+255). The following command will stack the F1 key (The HELP key for 4DOS): GET U 314 GET U Keyboard BUffer Page 43 3. Some programs pause when they are loading and require the user to press a key to continue. If the program does not clear the keyboard buffer, then GET U can stack the keystroke(s) to automate the loading of the program. It could also automate the first few program command keys. In this example we will stack the characters to bring up a spreadsheet file list in Quattro Pro. Rem /FR is the Retrieve command for Quattro Pro GET U "/FR" Rem Now call Quattro Pro - the spreadsheet list will be displayed. Q Page 44 Shift Locks GET UE GET UE Shift Locks Syntax: GET UE [/Wnum] [/switches] Input: numerical code to set or clear keyboard locks. /switches /M /V /W Output: ErrorLevel - Old value Environment - Old value UE will let you adjust the Caps, Num, and Scroll Locks. Sum the numbers for Scroll=16, Num=32, Caps=64 for the Locks you want to set. The other(s) will be cleared. You must use GET UE /Wnum not just GET UE num. CAUTION: Don't forget the /W. EXAMPLES 1. Turn off NumLock and ScrollLock, turn on CapsLock GET UE /W64 2. Turn on both NumLock and CapsLock, turn off ScrollLock. Rem Turn on GET reporting feature SET GET?=ON GET UE /W96 The Environment is: 64 The ErrorLevel is: 64 3. Turn off all key locks GET UE The Environment is: 96 The ErrorLevel is: 96 Rem Turn off GET reporting feature SET GET?= 4. Turn on CapsLock, then restore original setting Rem Turn on Caps and Num Locks to get user input Rem Save original setting in LOCK. GET UE /W96 /VLOCK= Rem Get string input from user in upper case and numbers. GET S "Enter information now: " Rem Restore original lock settings GET UE /W%LOCK% Rem Clear out the LOCK variable SET LOCK= GET.DOC Get DISK and FILE Information Page 45 GET DISK and FILE Information The commands K, Q, L, F, and Y obtain information about disks and/or files. Note that Q, K, and L check to see if the drive contains a formatted disk, and they return an ErrorLevel 0 if it does not. This avoids the Abort, Retry, etc. error handling. If the ErrorLevel is 0 the error code will be in %GET% as a hexadecimal value. Some error code values of interest are: 0 - Write protected diskette (n/a since GET does not write) 1 - Invalid drive letter 2 - Drive not ready - no disk or door open. 4, 6, 7, 8, & B - Disk read errors C - General, nonspecific error. F - Invalid disk change GET K Get disk free space Syntax: GET K[E] [drive][/Wdiv] [/switches] Input: drive letter and optionally divisor /switches - /M /V /L /W Output: ErrorLevel - KiloBytes/10, KE - KiloBytes/100 Environment - KiloBytes K takes the argument to be a drive letter. The colon is not required. The default is the current drive. Optionally a divisor can be included after the /W switch. K, as well as Q and L, starts out by attempting a direct read of the disk. If this fails by reason of one of the errors mentioned above, GET reports the error and exits. This avoids the annoying "Abort, Retry, Ignore, Fail?" message if the drive is not ready for some reason, and lets the BATch programmer handle the error as appropriate to the ap- plication. If the read is successful, GET K obtains the disk informa- tion and calculates the free space. Disk free space is reported in kilobytes (kb) in the Environment. To verify the value you can take the free space reported by CHKDSK and di- vide it by 1024, the number of bytes in a kb. The result should come out exactly. The value reported in the Environment is the same for GET K and GET KE. Since the ErrorLevel can only report numbers up to 255, GET reduces the value that is reported, but this does not affect the value in the En- vironment. For GET K the number of kb is divided by 10, and for GET KE, the kb is divided by 100. For disks with very large partitions, this may still not reduce the amount reported below 255, so GET also has pro- visions for an optional programmer supplied divisor. For example, an argument of /W1024 will divide by 1024, and the ErrorLevel will contain approximate megabytes of free space. The /W notation is the new preferred method. EXAMPLES: 1. Assume that CHKDSK reports "8,386,560 bytes available on disk". Then GET K reports Rem Turn on GET reporting feature Page 46 Get disk free space GET K SET GET?=ON GET K The Environment is: 8190 The ErrorLevel is: 255 In this case 8190 divided by 10 is 819, a figure too large for the Error- Level, so the ErrorLevel is set to the maximum value. 2. Same assumption as 1. GET KE reports GET KE The Environment is: 8190 The ErrorLevel is: 81 In this case the kb is divided by 100 and truncated by integer arithmetic to 81. 3. Same assumption as 1. Suppose we want the free space in megabytes (mb) on drive C:. GET K C /W1024 The Environment is: 8190 The ErrorLevel is: 7 In this case, 8190 divided by 1024 is just under 8, but is truncated to 7 by the integer arithmetic used. The BATch file is assured of at least 7 mb free. 4. Obtain the free space on the diskette in drive B. Assume that CHKDSK reports 700,416 free. GET K b The Environment is: 684 The ErrorLevel is: 68 Rem Turn off GET reporting feature SET GET?= 5. There is no diskette in drive A:. The error may be reported as 2 or C. GET K A if not errorlevel 1 if not "%GET%"=="" goto DiskError Echo The free space on drive A: is %GET% goto exit :DiskError Echo Disk error %GET% on drive A:. :exit GET Q Get Disk Capacity (Quota) Page 47 GET Q Get Disk Capacity (Quota) Syntax: GET Q[E] [drive][/Wdiv] [/switches] Input: drive letter and optionally divisor /switches - /M /V /W Output: ErrorLevel - KiloBytes/10, QE - KiloBytes/100 Environment - KiloBytes Q reports the capacity of a disk. GET Q works just like GET K except that it returns the capacity of the disk as if it were empty. Q for Quota? As with K, Q first determines that a formatted disk is present in the drive. Q will most often be used to determine the type of diskette in a floppy disk drive although it will work on a hard disk as well, if that is of interest. Before Q can make this determination, the disk must be formatted, so it cannot be used to select the type of formatting to use in a BATch file. For both Q and K the extended command divides the ErrorLevel by 100 but does not change the Environment variable. If you need a different divisor for the ErrorLevel for K or Q, you can use the /W notation. This divisor feature will be needed to get ErrorLevel information on large partitions. EXAMPLES: 1. A 360k diskette is in drive A:. CHKDSK reports "362,496 bytes total disk space". Rem Turn on GET reporting feature SET GET?=ON GET Q A The Environment is: 354 The ErrorLevel is: 35 That's right, in computer terms there are only 354kb on a nominal 360k diskette after space is set aside for the boot record, FAT, and root directory. By the way, I think you will find that GET reports faster than CHKDSK in spite of taking time to try the direct read to check for drive ready. 2. A 1.2mb diskette is in drive A:. CHKDSK reports 1,213,952 total. GET QE A The Environment is: 1185 The ErrorLevel is: 11 3. A 720k diskette is in drive B:. CHKDSK reports 730,416 bytes. GET Q b The Environment is: 713 The ErrorLevel is: 71 4. A 1.44mb disk is in drive B:. CHKDSK reports 1,457,664 total bytes. GET Q B The Environment is: 1423 Page 48 Get Disk Capacity (Quota) GET Q The ErrorLevel is: 142 5. CHKDSK reports 33,449,984 bytes total disk space on drive C:. Use GET to find the number of megabytes in the ErrorLevel. GET Q c /w1024 The Environment is: 32666 The ErrorLevel is: 31 Rem Turn off GET reporting feature SET GET?= 6. There is no drive Z:. The error may be reported as 1 or C. GET Q Z if not ErrorLevel 1 if not "%GET%"=="" goto DiskError Echo The disk in drive Z: has %GET% kilobyte capacity goto exit :DiskError if %GET%==1 Echo Invalid drive letter: Z. if %GET%==C Echo General failure on drive Z. :exit GET L Get volume label Page 49 GET L Get volume label Syntax: GET L [drive] Input: optional drive letter /switches - /M /V /U /L Output: ErrorLevel - 1=label found, 0=no label found Environment - Volume Label L gets the Volume Label of the specified disk. The ErrorLevel is 0 if the disk is not labelled, or 1 if the disk has a volume label. The optional argument is the drive letter, defaulting to the current drive. If the disk is not labelled, the GET variable will be expunged and the Error- Level will be 0. Volume labels can be placed on disks when they are formatted by using the /V switch with the FORMAT command, or later by using the DOS LABEL com- mand, or other labelling utility. Volume labels can be very useful in identifying and cataloging diskettes, especially when they can be checked automatically with a program such as GET. Another use is to verify that the user has inserted the correct diskette when running an installation BATch program. Volume labels can be up to 11 characters. DOS will allow any of the 256 ASCII and extended characters except ."/\[]:*|<>;,?, ASCII 0-31, and the lower case alphabetic characters. (Actually some LABEL programs allow lower case and other characters such as the decimal point, but since DOS converts lower case to caps and will not allow some characters it is better to stick with caps and standard DOS labels.) Even the space character is allowable in a Volume label. Therefore, with 184 charac- ters to choose from, there is an almost endless set of combinations that you can use. To enter the extended characters above 127 hold down the Alt key while typing the ASCII code on the number pad keys. (On some systems it is necessary to hold down both the Alt and the Shift keys while typing an extended character. You may be able to enter ASCII 127 with the Ctrl-BackSpace key.) The file SCANCODE.DOC with the registered version contains a table of all the ASCII characters. It is often convenient to have a space in a volume label, but most ver- sions of DOS make it difficult to verify such a label with the BATch IF subcommand. To DOS the space is a delimiter, and the IF comparison will fail, usually with some message such as "Bad command or file name". To work around this problem, GET provides a method to compare a string, which may include one or more spaces, with the volume label of a disk by using the LE command. The test label is given in the argument and must be enclosed in double quote characters. The comparison is exact and case sensitive, so get it right the first time. If the string is less than 11 characters long, do not include any trailing spaces to fill in the 11 characters. Only the characters up to the last non-space charac- ter will be checked and additional spaces will cause the comparison to fail. If you need to test with the IF subcommand, the /U switch will force lowercase letters (if any) to uppercase, and will convert spaces to ASCII 255 characters. EXAMPLES: 1. The disk in drive B: does not have a volume label. Rem Turn on GET reporting feature Page 50 Get volume label GET L SET GET?=ON GET L B The ErrorLevel is: 0 2. The disk in drive A: has the volume label BOB STEPHAN. GET L A The Environment is: BOB STEPHAN The ErrorLevel is: 1 3. The disk in drive A: is not formatted. The error may be reported as 'C' or one of the read error codes above. Even though there is a value in the environment, the ErrorLevel of 0 is sufficient to determine that the disk does not have a volume label. GET L A if not errorlevel 1 goto NoLabel Echo The label on the disk in drive A: is %GET% goto exit :NoLabel if not "%GET%"=="" goto DiskError Echo There is no volume label on the disk in drive A: goto exit :DiskError Echo Error %GET% reading disk in drive A: :exit GET LE Match volume label Page 51 GET LE Match volume label Syntax: GET LE "label" [drive] Input: "label" for LE to match, optional drive letter /switches - /M /V /U /L Output: ErrorLevel - 1 =yes, 0=no Environment - Volume Label LE takes a trial label in the "label" argument and sets the ErrorLevel to indicate whether the disk label matches. The comparison is case sensi- tive and there must not be any trailing blanks in the "label" argument. The /U and /L switches affect only what is placed into the Enviroment string and do not affect the comparison. EXAMPLES: 1. Compare the volume label on the disk in drive A: with the string "BOB STEPHAN" GET LE "BOB STEPHAN" A The Environment is: BOB STEPHAN The ErrorLevel is: 1 2. Compare the volume label on the disk in drive A: with the string "BOB" GET LE "BOB" A The Environment is: BOB STEPHAN The ErrorLevel is: 0 Rem Turn off GET reporting feature SET GET?= Page 52 Get file size GET F GET F Get file size (DIR=0) Syntax: GET F[E] filespec [/switches] Input: file specification including path but no wildcards. /switches /M /V /L /X /W /A Output: ErrorLevel - F: KiloBytes; FE: KiloBytes/10. With /A: Bytes (up to 255). Environment - file size in KiloBytes, Bytes, or Hex bytes The file specification (filespec) is not in quotes and must not contain wild card characters, but may contain drive and path information. F reports file size. The result is reported as kilobytes which allows sizes up to 261,120 bytes to be reported in the ErrorLevel. For FE the divisor is 10 so that files up to 2,611,200 bytes can be reported in the ErrorLevel. The /Wnum switch can be used to specify a divisor other than 10 for either F or FE in the same manner as for GET K and GET Q. The size in kilobytes will be divided by the divisor and the result placed in the ErrorLevel. These divisions affect the ErrorLevel only, the value in the Environment will not be changed. Values in the En- vironment can be up to 655,530 kilobytes. If it is possible to have larger files on your system, the value for larger files will have an asterisk as the last character indicating that the value is not valid, but is larger than 655,530 kilobytes (671,262,720 bytes). If /A is specified, All the bytes in the file size will be reported in the Environment for files up to 655,350 bytes. If over that size, the value will have an asterisk as the last character indicating that the size is not valid, but that it is larger than 655,350 bytes. If the file is 255 bytes or less, the full size will be in the ErrorLevel. The /Wdiv switch can be used to specify a divisor for larger files so that the resulting ErrorLevel will be less than 255. The divisor does not affect the Environment variable. The /X switch can be used to cause the exact file size to be reported in the Environment in hexadecimal as was done in versions prior to 2.5. If the filespec cannot be found, the GET variable will be expunged from the Environment and a standard DOS error code will be returned in the ErrorLevel. The error codes of special interest are: 2 for "File not found" 3 for "Path not found" 15 for "Invalid drive" Directory existence: The F command for GET Filesize can be used to determine whether a named directory exists. As usual, if the filespec is a directory, the ErrorLevel will be 0 and the Environment variable will be '0'. For example: GET F "d:\mydir\xxx" will return 2 if the path is found but not the file named XXX, a 3 if the path D:\MYDIR is not found, or a 15 if there is no D: drive. GET F "d:\mydir" will return either 2 or 15 since it is not clear whether MYDIR is supposed to be a file or a path. Whenever the item specified in the filespec may not exist, always check for an empty GET variable (IF "%GET%"=="") which indicates that an error code is in the ErrorLevel. GET F Get file size Page 53 NOTE: The use of GET F to test for the existence of a directory is valid only for subdirectories, and not for a root directory. Since DOS does not recognize the root directory as a file, commands such as GET F \, GET F c:\, GET F c:, etc. are not valid. Also, although it is a docu- mented procedure in MS DOS 5.0, do not use the NUL device to check for a directory if any users might be using DR DOS 5.0. DR DOS 5 thinks that the NUL (and other) devices exist even in non-existent directories. It may be that a few other versions of DOS do not support the NUL device method of checking, but GET will work with them all. Device Drivers: GET F can be used as a means of communication between your CONFIG.SYS and your AUTOEXEC.BAT. GET F will take the name of a device driver that may have been loaded in CONFIG.SYS and check to see if it has, in fact been loaded. The response will be similar to that for a DIR; i.e. if the driver is loaded, 0 in the ErrorLevel and "0" in the Environment. If the driver is not loaded, the Environment variable will be empty, and the ErrorLevel will contain an error code, usually 2. CAUTION! The name you use for the driver must be the INTERNAL name, not necessarily the same name you use in CONFIG.SYS. Most memory mapping commands and programs will show the internal name that you must use. This method will not work for ANSI.SYS and its clones because they use the name CON, but GET A is available to determine whether ANSI.SYS is loaded. (With all that said, it is only fair to point out that you can accomplish the same effect with IF EXIST by using the internal name of the device driver.) EXAMPLES: 1. Check to see if the device QEMM is loaded. The internal name for QEMM is QEMM386$. In this example, the driver is loaded. Rem Turn on GET reporting feature SET GET?=ON get F QEMM386$ The Environment is: 0 The ErrorLevel is: 0 2. Same example, but QEMM is not loaded. get F QEMM386$ The ErrorLevel is: 2 3. Check for the existence of a directory named D:\QPRO\WQ1. IN this ex- ample the directory exists. GET F D:\QPRO\WQ1 The Environment is: 0 The ErrorLevel is: 0 4. Same example, but the directory does not exist. The ErrorLevel is reported as 2 meaning "File not found" because it cannot be determined of WQ1 is a file or a subdirectory. GET F D:\QPRO\WQ1 The ErrorLevel is: 2 5. Suppose a file named d:\qpro\wq1\taxes.wq1 is a valid file name. Using GET F to get the file size could produce any of the following results. Page 54 Get file size GET F Rem If you enter an invalid directory: GET F D:\QPRO\WQ\TAXES.WQ1 The ErrorLevel is: 3 Rem If the file does not exist after all: GET F D:\QPRO\WQ1\TAXES.WQ1 The ErrorLevel is: 2 Rem If the file is found to have 23,129 bytes: GET F D:\QPRO\WQ1\TAXES.WQ1 The Environment is: 23 The ErrorLevel is: 23 GET F D:\QPRO\WQ1\TAXES.WQ1 /X The Environment is: 5A59 The ErrorLevel is: 23 Rem Turn off GET reporting feature SET GET?= 7. Suppose you have a file of exactly 166,816 bytes. You could see the following results. GET F filespec The Environment is: 163 The ErrorLevel is: 163 GET F filespec /A The Environment is: 166816 The ErrorLevel is: 255 GET F filespec /A /W1000 The Environment is: 166816 The ErrorLevel is: 166 GET F filespec /A /W1000 /X The Environment is: 28BA0 The ErrorLevel is: 166 7. Suppose we have a file we want to copy to drive B:, but we want to check if there is enough space for it. Note that file size is rounded up and disk space is truncated by integer arithmetic so the result here will err on the safe side if at all. Since GET F reports kilobytes in the ErrorLevel, and GET K reports kilobytes in the Environment, we can test as follows: GET F Get file size Page 55 @echo off Rem First get the disk free space on drive B: and save it in FREE= get k b /VFREE= Rem Check for error if not errorlevel 1 goto error Rem Now get the size of the file and check if there is enough room. get f filename.ext Rem Check for error if "%GET%"=="" goto error Rem If the ErrorLevel is not greater than the free kilobytes goto sizeok. if not errorlevel %FREE% goto sizeok Echo There is insufficient space on Drive B: for filename.ext. goto exit :sizeok copy filename.exe b: goto exit :error Echo An error has occurred :exit Rem Clear out the FREE variable SET FREE= Page 56 Current Directory GET Y GET Y Get current directory Syntax: GET Y[E] [drive for Y] [/switches] Input: optional drive letter for Y, none for YE /switches /M /V /L Output: ErrorLevel - Y: directory level, root=0; YE: current drive, A=0. Environment - directory path (Y) or drive letter (YE). Y gets the current directory for the default or a specified drive. It takes an optional drive letter argument (the : is not necessary) which defaults to the current drive if omitted. The ErrorLevel reports the directory level - 0 = root directory, 1 for first subdirectory level, etc. Note that DOS maintains a "current directory" for each drive, not just for the logged drive, so it makes sense to inquire about the cur- rent directory on a drive other than the logged drive. YE returns the current (or logged) drive. The drive letter is in the En- vironment, and the drive number in the ErrorLevel - 0=A, 1=B, etc. EXAMPLES: 1. Suppose the following conditions exist - logged drive is C:, current directory on C: is C:\DOS, current directory on D: is D:\QPRO\WQ1, there is no E: drive, a floppy disk with no subdirectories is in B:. GET com- mands will report as follows: Rem Turn on GET reporting feature SET GET?=ON GET Y The Environment is: \DOS The ErrorLevel is: 1 GET Y D The Environment is: \QPRO\WQ1 The ErrorLevel is: 2 Rem Get the current drive and directory, and combine them to make Rem a full path that does not end in a trailing backslash. GET YE /VDIR= The Environment is: C The ErrorLevel is: 2 GET Y The Environment is: \DOS The ErrorLevel is: 1 if not ErrorLevel 1 set GET= SET DIR=%DIR%:%GET% GET Y B The Environment is: \ The ErrorLevel is: 0 Note: The root directory is the only case that GET ends the Environment variable with the \ character. (It is easier to add one than to drop it off.) GET Y E The ErrorLevel is: 0 Turn off GET reporting feature SET GET?= GET Y Current Directory Page 57 2. You can "and" ErrorLevel checks together to check for a specific value. In this example, use ErrorLevel to see if the current drive is B:. GET YE Rem if it is at least 1 and not 2 or more, Rem then it is exactly 1 meaning B:. if ErrorLevel 1 if not ErrorLevel 2 goto ISB Echo The current drive is not B: goto exit :ISB Echo The current drive is B: :exit Page 58 Get MEMORY and SYSTEM Information GET.DOC GET MEMORY and SYSTEM Information The commands BR, P, E, M, D, 4, 7, and A obtain information about the opera- ting system and hardware configuration. GET BR Get/Set Break Flag Syntax: GET BR [New flag] [/switches] Input: optional new flag - 1 = ON, 0 = OFF. /switches /M /V Output: ErrorLevel - old break flag Environment - old break flag GET BR checks and/or sets the DOS BREAK Flag. It works like some of the other get/set commands such as B and V. GET BR will report 1 if the BREAK Flag is ON, or 0 if it is OFF. In addition, GET BR 1 will turn it on, and GET BR 0 will turn it off. Although you can control BREAK with the DOS BREAK command, GET BR allows you to store the user setting and temporarily change it to suit your programming style. Of course, if you allow the user to BREAK out of your BATch file with DOS Ctrl-Break hand- ling, you will not have the opportunity to reset it, but if you want to handle BREAK yourself and use /C regularly, then you can get, set, and restore the user BREAK Flag with GET BR. GET BR also gives you another method of communicating information from your CONFIG.SYS to your AUTOEXEC.BAT. You can set BREAK ON or OFF in CONFIG.SYS according to whatever you want it to mean, and use GET BR to check and optionally reset it in your AUTOEXEC.BAT, then take some ac- tion according to whether it was ON or OFF. EXAMPLES: 1. Save user Break flag setting so you can turn it off to help you do your own Ctrl-Break management with the /C switch. When finished, restore user's original flag setting. Rem set BREAK OFF and save old setting in variable BREAK=. GET BR 0 /VBREAK= Rem Now do whatever you want in the BATch file, such as: GET S "Enter your password: " /c Rem When finished, restore saved Break flag setting. GET BR %BREAK% Rem Don't forget to clear out the variable! SET BREAK= 2. Suppose in one CONFIG.SYS file you have BREAK=ON to indicate that you are configuring for your CAD program, and in another CONFIG.SYS file you have BREAK=OFF if you want to run your normal configuration. In your AUTOEXEC.BAT you can test the Break flag, set it to the setting you want, and take appropriate action, thus using just one AUTOEXEC for both configurations. Rem Get break flag setting and turn it off. GET BR 0 if "%GET%"=="1" goto RUNCAD Rem Do your something else here. goto EXIT :RUNCAD Rem Run your CAD program here. :EXIT GET P Check for Printer(PRN) Page 59 GET P Check for printer(PRN) Syntax: GET P[E] [/switches] Input: none /switches /M /V Output: ErrorLevel - 1=yes, 0=no Environment - 1=yes, 0=no P checks whether a printer is available and ready at LPT1 (PRN). 1=yes, 0=no. PE will also send the DOS BIOS initialization signal to the printer as it does during boot-up. This may not work if a print buffer or spooler is in use unless it can be bypassed. If your printer has an internal buff- er this is a way to flush it. If PE reports no printer, then the print- screen operation (the Print Screen or Shift PrtSc key) will be disabled to prevent hanging the computer if the PrtSc key is inadvertently pressed. To enable print-screen again, run GET PE with a printer at- tached and ready. EXAMPLES: 1. Check to see if a printer is available. GET P if ErrorLevel 1 goto PRINTIT Echo Can't print, no printer available. goto EXIT :PRINTIT copy filename.ext prn :EXIT 2. Initialize printer, clearing the buffer and setting the page setting to Top of Form (TOF). If no printer is available, the Print Screen func- tion will be turned off. GET PE if ErrorLevel 1 goto PRINTIT Echo Can't print, no printer available. Echo The print screen function has been disabled. goto EXIT :PRINTIT Echo The printer has been initialized, internal buffer cleared. :EXIT Page 60 Get Environment Left GET E GET E Get Environment Left Syntax: GET E[E] [/switches] Input: none /switches /M /V Output: ErrorLevel - number of Environment bytes free, EE divides by 10. Environment - number of Environment bytes free E reports the number of bytes of Environment space available. If it might be over 255 use EE which divides the number of bytes by 10 for the Er- rorLevel only, and can report up to 2550 bytes. Since GET makes ex- tensive use of the Environment, it is always a good idea to use GET E at the beginning of the BATch file to determine whether there are enough bytes available for the use of GET in the BATch file. EXAMPLES: 1. Suppose GET will require at least 15 bytes of Environment space for the variables it will create in your BATch file. Remember to include the space required by the variable name, the = sign, and a terminating zero byte that is automatically added internally. GET E if ErrorLevel 15 goto CONTINUE Echo Not enough free Environment space to run this BATch file. goto EXIT :CONTINUE Rem Continue with the BATch file :EXIT 2. A more primitive method of checking for environment space is to attempt to create a variable then see if it is there. This may result in the user seeing an "Out of environment space" message. Rem Try to create a variable that will use 16 bytes of space. SET TEST=1234567890 if "%TEST%"=="1234567890" goto CONTINUE Echo Not enough free Environment space to run this BATch file. goto EXIT :CONTINUE Rem Don't forget to clear out your test variable SET TEST= Rem Continue with the BATch file. :EXIT GET M Get Memory Free Page 61 GET M Get Memory Free Syntax: GET M[E] [/switches] Input: none /switches /M /V Output: ErrorLevel - number of kilobytes free, ME divides by 10. Environment - number of kilobytes free M reports the free memory available in kilobytes. ME divides by 10. EXAMPLES: 1. A BATch file can check if there is sufficient memory to run a pro- gram. GET M if errorlevel 150 goto CONTINUE Echo Not enough memory to run your program. goto EXIT :CONTINUE Rem Run your program here. :EXIT 2. Suppose your program requires 300kb of memory. GET ME if errorlevel 30 goto CONTINUE Echo Not enough memory to run your program. goto EXIT :CONTINUE Rem Run your program here. :EXIT Page 62 Get DOS Version GET D GET D Get DOS Version Syntax: GET D[E] [/switches] Input: none /switches /M /V Output: ErrorLevel - First two digits of DOS Version times 10. Environment - Major Version, DE gives Minor Version. D reports the DOS version. The ErrorLevel will contain a number such as 33 for DOS 3.3 and 3.31, or 50 for DOS 5.0. The Environment will con- tain the major version such as 3 for DOS 3.0, 3.1, 3.3, or 3.3. DE will report the minor version in the Environment such as 1 for DOS 3.1 or 0 for DOS 5.0. EXAMPLES: 1. You're setting up a program for your clients and it requires something different depending on whether the DOS Version is later than or earlier than 3.1. GET D if ErrorLevel 31 goto DOS3 Rem Do what you need here for DOS 2.x or 3.0. goto EXIT :DOS3 Rem Do what you need here for DOS 3.1 and later. :EXIT 2. You are distributing a program that requires DOS 3.3 or later. GET D if ErrorLevel 33 goto DOSOK Echo This program requires DOS 3.3 or later. goto EXIT :DOSOK Rem Run your program here. :EXIT GET 7 Check Coprocessor Page 63 GET 7 Check Coprocessor/CPU Syntax: GET 7[E] [/switches] Input: none /switches /M /V Output: ErrorLevel - 7: Math Coprocessor Installed - 7E: type of CPU. Environment - Character representation of ErrorLevel number. 7 reports whether a math coprocessor is installed. 1=yes, 0=no. 7E reports the CPU chip type - 0 for 8088/86, 2 for 80286, or 3 for 80386 or later. EXAMPLES: 1. Run a faster version of a mathematical program if a coprocessor is in- stalled. GET 7 if ErrorLevel 1 goto NDP Rem Run the slower version here goto EXIT :NDP Rem Run the faster version here :EXIT 2. Run the 386 version of a program if the CPU is an 80386 or later. GET 7E if ErrorLevel 3 goto IS386 Rem Run the non-386 version here goto EXIT :IS386 Rem Run the 386 version here :EXIT Page 64 Check 4DOS/Windows GET 4 GET 4 Check 4DOS/Windows Syntax: GET 4[E] [/switches] Input: none /switches /M /V Output: ErrorLevel - 4: 4DOS - 7E: Windows. Environment - Character representation of ErrorLevel number. 4 Checks whether 4DOS or [4E] Windows is currently running. 1=yes, 0=no. Some DOS commands, such as CHKDSK, must not be run if Windows is run- ning. You can use this command to avoid these problems. 4DOS provides a method to make this check directly with BATch commands. It may be a convenience to use GET to get and store the information in the same command. 4DOS provides a lot of services for BATch files, and some DOS-like commands have extra features, but if the BATch file might be run on a system that is not using 4DOS for the command processor those extra features can't be used. EXAMPLES: 1. If 4DOS is the command processor, use some of its special features. If not, make do the best you can with COMMAND.COM and GET. Rem Find out if 4DOS is running and store the information. GET 4 /V4DOS= if "%4DOS%"=="0" goto to MSDOS Rem Run your 4DOS enhanced commands here. goto EXIT :MSDOS Rem Do the best you can with MS DOS and GET here. :EXIT Rem Clear out the 4DOS variable SET 4DOS= 2. Make a cover for CHKDSK to avoid damaging your disk if Windows is run- ning. Since CHKDSK is an external command, you can rename it to some- thing else to avoid running it inadvertently. Suppose we rename it CHEKDISK.EXE and call this BATch file CHKDSK.BAT. @Echo off Rem This file is CHKDSK.BAT, a cover for DOS CHKDSK. get 4E if ErrorLevel 1 goto WINDOWS CHEKDISK %1 %2 %3 goto EXIT :WINDOWS Echo Don't run CHKDSK when WINDOWS is running! :EXIT GET A Check for ANSI.SYS/Model Page 65 GET A Check for ANSI.SYS/Model Syntax: GET A[E] [/switches] Input: none /switches /M /V Output: ErrorLevel - A: ANSI.SYS - AE: ROM BIOS Model Byte Environment - A: 1=yes, 0=no - AE: Hexadecimal Model Byte A reports whether ANSI.SYS is loaded. If you are using an ANSI.SYS clone, check to see if it works with yours. AE will return the ROM BIOS model byte. At this time the documented model bytes listed in "The NEW Peter Norton's Programmer's Guide to the IBM PC and PS/2," (Page 64) are: FF(255)=PC(1981) FE(254)=PC or PC/XT(1982) FD(253)=PCjr(1983) FC(252)=PC/AT(1984-85),PC/XT Model 286(1986),PS/2 Model 50/60(1987) FB(251)=PC/XT(1986) FA(250)=PS/2 Model 25(1987)/30(1986) F9(249)=PC Convertible F8(248)=PS/2 Model 80(1987) (Example: My 80386 AT clone is an FC). EXAMPLES: 1. If the computer is running ANSI.SYS you can use it to provide special screen effects. For example, 4DOS has commands that take advantage of the features of ANSI.SYS that won't work if ANSI.SYS isn't loaded. Rem Check for ANSI.SYS and store the result in ANSI= GET A /VANSI= 2. If you are supporting several computers and they are different models, you may be able to determine which one is running the BATch file by reading the model byte. GET AE if "%GET%"=="FC" goto ATCLONE if "%GET%"=="F9" goto CONVERT if "%GET%"=="FD" goto PCJR Rem Do things for other computers here goto EXIT :ATCLONE Rem Do things for AT Clone here goto EXIT :CONVERT Rem Do things for IBM Convertible here goto EXIT :PCJR Rem Do things for the PC Jr. here :EXIT Page 66 Warm/Cold Boot GET W GET W Warm/Cold Boot Syntax: GET W[E] [arg] [/switches] Input: any argument to just report type of last boot. /switches /M /V Output: ErrorLevel - If arg, 1=warm, 0=cold Environment - If arg, 1=warm, 0=cold W will reboot the computer as if the 3-finger salute (Ctrl-Alt-Del) was pressed unless an arg is given. WE will reboot as if the computer was turned off then on again unless an argument is given. If any characters are present as an argument with W or WE, GET will at- tempt to determine if the preceding boot was warm or cold instead of rebooting. This does not work on all machines. It depends on whether the booting procedure clears a certain memory location - it worked on my XT but not on my 386, for example. If successful, a 1 indicates the previous boot was warm, 0 means it was a cold boot. EXAMPLES 1. Copy in a new AUTOEXEC.BAT and CONFIG.SYS and warm boot. copy autoexec.new autoexec.bat copy config.new config.sys get w 2. Ask for a password, if it is wrong cold boot the computer. get S "Enter password now: " TTTTTTTT if "%GET%"=="PASSWORD" goto OK get we OK: Rem Password was correct, continue. 3. Perform a CHKDSK if a cold boot but not a warm boot - may only work on XT class machines. GET W xxx if ErrorLevel 1 CHKDSK GET.DOC The Environment and Shells Page 67 Environment and Shells This is a brief, general discussion of the DOS Environment for those who may not be sufficiently familiar with it. For a more extensive discussion of the Environment, see Appendix A in the printed documentation provided with the registered version. The DOS Environment is a small area (usually) of memory that DOS automat- ically allocates to every program that it is asked to load or run. The "master" Environment is the original Environment allocated to COMMAND.COM or 4DOS or whichever command processor you are using. The original size of the Environment can be set in later versions of DOS by using the SHELL command in your CONFIG.SYS file. However, the setting of Environment size is not a SHELL command function, but is a command processor option. For example, the COMMAND.COM /E: switch lets you set the size if you are using COMMAND.COM as your command processor. For documentation look under such topics as SHELL, COMMAND, and "Configuring Your System" in your DOS manual. Since most new programs make extensive use of the Environment, it is important to be sure enough Environment space is allocated to accom- modate them all. If you see the error message "Out of Environment Space", you know that you do not have enough allocated. You can view the contents of the Environment by issuing the SET command of DOS with no arguments at the DOS prompt. You will see a sequence of variable names, each followed by the "=" sign and the string value as- signed to the variable. For example, COMSPEC=C:\COMMAND.COM. You can also store string information in the Environment with the SET command by specifying it in the same manner as it is displayed. For example, SET PATH=C:\;C:\DOS. Do not place any spaces on either side of the "=" sign unless you intend for the space to be either a part of the variable name or a part of the string. When DOS loads and runs a COM or EXE program file, that program receives a copy of the Environment as it is at that time, trimmed down so that only a few bytes remain free. This copy does not change unless the program that owns it changes it. Note that some DOS "shells" shield the master Environment from programs that are executed by the shell. If you find that to be the case, the in- formation will usually be available to the BATch file from the Environment of the secondary command processor loaded by the shell as is usually necessary to run a BATch file. Except for the /M switch, GET only at- tempts to locate the Environment of the command processor that is running the BATch file, so the Environment information can disappear if the shell or the secondary command processor is terminated. GET attempts to place the information where the BATch file can locate it since that is its pri- mary purpose. Also, when running from a shell there may be problems with "Out of Environment space" since DOS does not usually allocate excess En- vironment space to child processes. 4DOS provides a means to ensure that copies of the Environment have sufficient space available. Check the doc- umentation for your shell program to see if it can make sufficient En- vironment space available. You can always ensure that GET has enough En- vironment space to store its results by establishing a dummy GET variable before loading any shells or other programs. The best way would be to do it in your AUTOEXEC.BAT. Simply insert the command SET GET=xxxxx...xxxx in your AUTOEXEC.BAT file with enough x's or other characters for the max- imum length input string you are expecting. Page 68 Program Information GET.DOC PROGRAM INFORMATION GET is programmed in assembly language for MS-DOS computers. It was as- sembled with Borland's Turbo Assembler, and compressed with a file com- pression utility. GET is designed to be small and fast to provide rapid response in BATch files and not take up too much room on floppy disks, consequently it does not do extensive error checking. Nothing in GET is known to cause harm, but if parameters are not used in accordance with the documentation the results may not be what you expect. GET is designed for productive use by BATch programmers, not for casual use from the keyboard. In most applications there will be no noticeable slowing down of BATch file execution due to the use of GET. Most versions of DOS read and ex- ecute lines of BATch files one at a time. This is the slowest part of the BATch execution process. Providing there are sufficient DOS buffers or a disk cache, GET will remain available in the buffers or cache in memory and execute instantaneously when loaded by DOS. Some additional speedup may be noticed if it is possible to locate GET.EXE and/or your BATch file on a virtual disk in RAM such as on a RAMDRIVE or VDISK. Some of the code for GET was adapted from the sample program named WHAT.ASM included with Microsoft Macro Assembler (MASM). The MASM docu- mentation declares that the sample programs are in the public domain. For examples of GET, look at the BATch files on the MASDIR disk mentioned be- low for the use of a similar program called SDL_GET. You can do a lot in BATch programming with this utility. LICENSING AND DISTRIBUTION Although this version of GET remains free for personal use for all to en- joy, if you like GET and would like to help support development of in- expensive software, please send a contribution to the address below. Thank you for any support you care to provide. If you send $15 or more (overseas $20 U.S. funds) you will receive the following benefits: The latest version of GET with any new features plus one free upgrade. A smaller runtime version to distribute with your BATch files. A single user license with no royalties for use of the runtime version. A >60 page user manual giving examples and more detailed explanations. Free support by BBS, mail, phone, CompuServe, or Genie (see below). Notification of new releases and upgrades after the first one. California residents please add 7.75% sales tax. See the SPECIAL OFFER below for a discount on registering both GET and MASDIR. If you have a modem, VISA and MASTERCARD registrations can be entered via NITELOG BBS, 408-655-1096. After completing the brief sign-on registra- tion, enter S for Script, then 3 for Script 3 and provide the requested information. If you like and use GET but can't send money, at least drop me a note and I'll put you on my list to receive new "freeware" releases as they become available. Your help in distributing new releases of GET will be ap- preciated. CORPORATE users must obtain a site license from me for in-house use. If GET is to be installed on 2 machines $25, 3 machines $35, plus $5 for each additional machine. None of the above licensing terms includes using GET in conjunction with the distribution of a commercial (retail) software product other than shareware, user-supported, or public domain software. GET.DOC Program Information Page 69 To use GET in conjunction with the distribution of a retail software pro- duct you must contact me to discuss terms. Licenses are available for up to 50 copies for $100, up to 500 copies for $200, unlimited copies for $500. Call or message me for quotes if you are interested. BBS SYSOPs, PC User Groups, and shareware authors and distributors are hereby granted a single user license to use GET for their own purposes and to freely distribute unmodified copies of this version of GET.EXE and the associated files in GET25.ZIP. If an unregistered version of GET is used in conjunction with the distribution of a shareware or public domain soft- ware product, the distribution disk must include GET25.ZIP. VENDORS who have my permission to distribute my shareware product MASDIR, also have my permission to distribute GET. Other vendors must contact me for permission by sending me a request accompanied with a current catalog or other list of offerings. REGISTERED users of GET may use and distribute GET in accordance with these rules. GETRUN.EXE is a runtime version of GET available only to registered users. It omits the online help screens and the debugging in- formation so is considerably smaller - under 4k compressed file size - and runs in less than 9k of memory. GET is not a TSR so the memory is in use only while GET is actually running. 1. GET.EXE may be freely distributed provided the distribution disk in- cludes all *.DOC and other GET distribution files. Such distribution must not include GETRUN.EXE under any name. 2. If you are a licensed user of GETRUN.EXE, up to the licensed number of copies of GETRUN.EXE may be renamed GET.EXE and used in conjunction with distributed BATch files, provided that neither GET.DOC nor GET25NEW.DOC are included on any disk in the distribution package. For non-commercial use, licensed users may use an unlimited number of copies. 3. GET.EXE must never be included in any distribution that includes GETRUN.EXE no matter what names are used for these files. If you have any questions, comments, or suggestions please contact me at: MOBY DISK: 1021 San Carlos Road, Pebble Beach, CA 93953 Phone: (408) 646-1899/1373. GENIE:MOBYDISK. COMPUSERVE:72357,2276 BBS: The Cricket 408-373-3773 /s/ Bob Stephan November 29, 1991 Now for the commercial If you like GET please try MASDIR! MASDIR (pronounced 'master') the MASter DIRectory System, is a general purpose sorted directory program with unique customization and disk label printing features. If you ever use DIR, you should do yourself a favor and take a look at MASDIR. MASDIR is not a "shell"! The main program, SDL.COM, is one of the best sorted directory programs anywhere. The setup program allows you to set the many defaults to your own specifications, including customizing the titles that appear in the header. In addition, you can print disk labels and/or sleeve inserts for 5.25" and 3.5" diskettes. This really saves you a lot of time when you are looking through your collection of diskettes for a particular file. They are all listed conveniently along with your own description in the title lines. You can also create disk file catalogs of your diskettes and directories that you can then annotate to describe individual files, and search with your editor or listing program. Page 70 MASDIR, The MASter DIRectory System GET.DOC Additional features include listing only subdirectories or not listing them at all, listing only files created today or within a specified peri- od, reverse sorting for any of the sort options, the amount of space a group of files will occupy for different cluster sizes, support for DR DOS and 4DOS, SETting defaults in the Environment, enter two file specifica- tions such as *.COM *.EXE, paging up and down in large directories, show only files that have not been backed up (archive bit set), and many more. As of the above date, the current release of MASDIR is Version 5.4. It is a shareware program that is available on bulletin boards, GENIE, Com- puServe, The Public (software) Library, PC-SIG, and from other distrib- utors of public domain and shareware programs. If you cannot conveniently locate a copy, I will be happy to send you one. Just contact me as indi- cated above. The registration fee for MASDIR is $19 including shipping and handling for the program, plus one unit of labels free. Please include $2 S&H only if you order any amount of labels. SPECIAL OFFER. Register both GET and MASDIR and take a 15% discount. Use the MASDIR order form and indicate that you want both MASDIR 5.4 and GET 2.5 for just $29, instead of MASDIR by itself for $19. Then complete the rest of the form for any other items you want. If you have a modem, VISA or MASTERCARD registrations can be entered via NITELOG BBS, 408-655-1096. After completing the brief sign-on registra- tion, enter S for Script, then 3 for Script 3. Thank you for your kind attention. /Bob/ November 29, 1991 Appendix A The DOS Environment Available in the manual for the registered version Appendix B ASCII and Scan Codes Available in the manual for the registered version